Maintaining the Wiki

A while ago we switched from supertuxkart.sourceforge.net to simply supertuxkart.net. But we also made a lot more changes: a new version of MediaWiki, a new skin, and, perhaps most importantly, no more open user registration.

Why? Well, there were a number of reasons. There was no quality assurance on the old wiki. The problem with running a website using wiki software is that it's still a wiki: anyone can edit it. If we had maintained a separate wiki, this might not have been quite such a problem, but as a result, the entire website looked unprofessional, confusing, and outdated.

Our new approach is to only allow a few select people have wiki accounts. We now have a service that automatically syncs the wiki content with GitHub, and you can fork the repository, submit pull requests, and file issue reports—all without allowing wiki account creation. This page covers how YOU can start contributing to keep the wiki organized, friendly, and up-to-date.

MediaWiki Markup

This website is powered by MediaWiki. Pages are written in MediaWiki's own markup language. Some basic formatting information can be found here.

To maintain a the same style throughout the wiki, as well as preserve mobile-friendliness, we do require a few restrictions on what markup you may use.

  • Use only level-2 headings and below (e.g. == Level 2 ==). Level-1 headings are for page titles only.
  • Use logical heading order.
  • When using tables in documentation, be sure that you are using the wikitable class:
  • Use packed MediaWiki galleries for images to preserve mobile-friendliness, unless images are extremely small:
  • To maintain readability of code,
    • Put an empty line above and below headings.
    • Put a space between heading markup (==)and headings.
    • Put an empty line above and below templates, unless avoiding whitespace
    • Avoid use of HTML wherever possible. Use empty lines to create line breaks rather than <br /> tags.

Maintaining Documentation

While most programming documentation uses Doxygen and therefore is not maintained on the wiki, all the artists' documentation is on this website, linked from the Art Portal.

Format of Artists' Tutorials

It's important to have a standard format for tutorials. Every tutorial has an index page titled "Making <Art type>" (e.g. Making Tracks). This page uses the Popup-prerequisite template, followed by a short introduction, a level 2 heading "Contents," and a series of bullet points with links to various chapters of the tutorial. Optionally, tutorials may have another level-2 heading and series of bullet points linking to appendices.

Modular Concept

Wherever possible, articles should not be tied to a specific tutorial. Materials, Texturing, and Special Effects are examples of articles that are part of multiple tutorials. On the other hand, keep content specific to a certain type of artwork in separate articles. These articles should have titles prefixed with the name of the tutorial (e.g. Making Tracks: Ideas and Concept Art).

Under certain circumstances, you may come across a subject which is partially relevant for one tutorial, and fully relevant for another. In such cases, you should write a full article about the subject for the tutorial to which it is most relevant, then surround the content relevant for both tutorials in <onlyinclude></onlyinlcude> tags, and transclude the content into an article of the less related tutorial.


An example of the above circumstances is lighting. It is most relevant for the Making Tracks tutorial, but the Making Library Nodes tutorial should also include a section about point lights and volumetric lighting. For this case, I wrote a full article about lighting for the track-making tutorial, Making Tracks: Sky and Lighting. However, I surrounded the section on point lights and the section on volumetric lighting in <onlyinclude></onlyinclude> tags, and transcluded these sections into the Making Library Nodes: Lights page, using the following markup:

Art Portal Navigation Template

We provide a template to be placed at the bottom of all art-related documentation. Please use it—it greatly improves navigation between articles. Add it to the bottom of any artwork documentation pages you create:

Style

While most of the visual style is provided by the wiki skin, some parts are your responsibility to get right.

Visual

Page Layout

All main pages (i.e. not documentation pages) must transclude the Generic-hide-summary template to remove the title and use the ArticleMainTitle template for any headings. These pages should not have a page title unless necessary. For example, the Download page's heading says "Get the latest version for your system!" instead of "Download." It's obviously the download page—a title would be redundant.

All documentation pages, like tutorials, guidelines, etc. use standard MediaWiki formatting, with the exception of any templates or pictures (which should use packed galleries, as mentioned above).

Templates

We provide several templates ready-to-use for articles. Please use them. They are:

  • Popup-warning: A blue box with the title "Info." Example:
  • Popup-code: A dark gray box with the title "code." Example:
  • Popup-prerequisite: A orange box with the title "Prerequisites." List links to articles that should be read before starting a tutorial using an unordered list inside this template. Example:
  • Legacy-warning: A red box with the title "Legacy." Used on pages in the Legacy namespace, which is for obsolete but possibly still useful pages. Example:
  • ArticleMainTitle: A title template, used for main pages and not documentation pages (see above). Example:
  • Faq-question: You can use this template to hide information until someone clicks on the "Expand" button. It's not only useful for FAQs—you can use it to organize lots of information that might only be relevant for a few people (e.g. operating system-specific instructions). Example:

Writing

It's important to keep the quality of contributions up. Better contribution moderating is one of the goals of the switch to GitHub. Here is a list of rules you need to follow:

  • You must follow English grammar rules to the best of your ability. If you are unable to, feel free to send in your pull requests, but we may require you to correct any issues before merging. We aren't terribly strict, but we will also willingly accept contributions to correct any mistakes.
  • Page titles should properly capitalized. A guide can be found here.
  • Write in clear, descriptive paragraphs and follow a logical sentence order. While it's useful to be concise, please spend time to make your writing completely understandable.
  • When providing instructions for computer programs such as Blender, use bold text for any user interface (UI) components and names. This improves readability and allows for experts to get through faster without confusing newbies.

Making Contributions

"Okay," you say, "I've read all these rules! Now how do I actually contribute?" It's simple, if you're familiar with Git: open an account on GitHub (if you don't already have one) and fork the repository that contains the content for this wiki. Make any changes you want, then submit a pull request to get your changes merged. The auto-deploy script runs whenever a commit is made on GitHub, so your changes should appear live within a minute or two! (Google is your friend if you need help with forking and pull requests.)

Files

Occasionally, you may need files uploaded to the wiki along with writing. These can be easily included in a pull request, just like text changes. Simply add a file to the repository (without the File: prefix). Spaces in the filename will automatically be converted to underscores on the wiki.

I don't know how to use Git!

We understand that not everyone has the time to learn Git. If you like, you may post your content on the forums under the contribution section. Please still use MediaWiki markup, however.

About the Auto-Deploy System

Every hour, the auto-deploy script checks for new edits on the wiki. It pulls any changes to a local repository, pulls changes from GitHub, and then pushes to both the wiki and GitHub. (That description is slightly simplified, but that's the general idea.) The script uses Git-MediaWiki to clone and pull changes from the wiki. Because the script has to query every page for changes, it takes approximately 2 minutes to get changes from GitHub to the wiki (and vice-versa).

The system also uses GitHub-Auto-Deploy to run the same script whenever there is a new commit made to GitHub.