|This page documents a MediaWiki development policy, crafted over time by developer consensus (or sometimes by proclamation from a lead developer).|
The MediaWiki software is developed collaboratively by hackers from all around the world. To make sure that none of WMF's dozens of wikis breaks by an upgrade, but to also make sure that all our wikis are reasonably up to date, we need a general development policy. This is outlined below.
Gerrit access[edit | edit source]
To gain access to Gerrit, our code review system, you can now register at wikitech:Special:UserLogin/signup. Previously you would have to apply at Developer access. Git with Gerrit is a lot like wiki with FlaggedRevs: Everything must be reviewed and approved, and can be reverted.
Unstable, the test server, and the REL* branches[edit | edit source]
Main development takes place in the master branch of Git; it is unstable, but should always be kept in a working state. See also +2. Major modifications should take place in a development branch or elsewhere.
Code is generally synced from Git WMF branch with the Test Wikipedia, the Test2 Wikipedia and MediaWiki.org before it goes live on other production sites, this is to ensure that everything isn't taken out by the update. It is important to remember that this is not a substitute for testing and all code should thoroughly be tested before being checked into Git master.
If you care about release management or want to try out one of the stabilized versions, the only branches that matter are those of the form REL*.
Typically there will be a testing phase when a new release is begun. At that point users will be pointed to test.wikipedia.org to try out all the new things. There might be a few release candidates, a 1.x.0 version, and finally a few minor bugfix releases.
Releases[edit | edit source]
Every few months, the stable branch should be packaged into a .tar.gz file and made accessible from the webserver. This ensures that users of our software can easily get a reasonably stable version without messing with Git. Anyone submitting patches should preferably use the latest version of master to avoid conflicts, and of course people with commit access need to use Gerrit to be able to push stuff for review. It's not advisable to run production wikis off of development versions unless you know what you're doing (as do, for instance, the Wikimedia tech staff, a number of whom are also MediaWiki developers).
The Release checklist provides a more comprehensive list of tasks to be done for a release.
Database patches[edit | edit source]
If you change the database schema, follow these rules:
- Update the installer – Please update includes/installer and add an appropriate SQL update file to maintenance/archives/. The naming convention, if you're adding a field, is patch-table-field.sql. If you're removing a field, it's patch-drop-table-field.sql. If you're adding a table, it's patch-table.sql. Look at the commit history of includes/installer/(MySQL|Postgres|SQLite|Mssql|Oracle)Updater.php to find examples of how it's done. The schema change must be done for all five database types, or the patch will be rejected. If you're adding a bunch of fields to the same table, make all those changes in one query in one patch file.
- Get your change approved by a DB admin – MediaWiki is deployed to Wikimedia websites every week, and it takes considerable planning to apply schema changes to MySQL-based sites the size of Wikipedia. As of November 2013, Sean Pringle (springle on irc) is the best person to add to database reviews.
- Make your schema change optional – All schema changes must go through a period of being optional. A couple examples:
- Instead of changing the format of a column, create a new column, make all writes happen to the old and new column (if it exists) and deprecate use of the old column. Check if the new column exists before blindly assuming that it does. Only eliminate support for the old column after it's clear the schema migration has happened and there's no chance that we'll need to roll back to the old version of the software. If this doesn't seem feasible, send mail to wikitech-l asking for advice.
- You could set your new feature to only work if a config option is set to true, and set the option to false by default. Then the commit can be safely scapped before the schema change is made. You'll then have to pester the sysadmins incessantly to get them to make the schema change, at which point you can remove the config option to enable your feature.
There might be cases where the "make your schema change optional" rule will be prohibitive from a performance or logistics perspective. However, schema changes like that should be rare to begin with, and should have prominent discussion on wikitech-l mailing list. In the case where it's impossible to make your schema change optional, it is still critical to write scripts to roll back to the pre-change state.
Once a migration has been reviewed, please update Schema changes page with all pertinent details, then get in touch for deployment scheduling. There are good and legitimate reasons to not follow the "make schema changes optional" policy but if that's the case, please provide 3–7 days of lead time, depending on the size of tables and number of affected wikis.
New database tables should contain a primary or unique key, at least whenever innodb is the database storage engine. Primary keys, and fields that reference them, should be unsigned, in order to increase the maximum values. For more details, see http://www.percona.com/files/presentations/WEBINAR-MySQL-Indexing-Best-Practices.pdf . Database optimization practices should also be followed.
Test wiki policy[edit | edit source]
There is an official test wiki at http://test.wikipedia.org. Some developers may also have test servers deployed.
Generally, the purpose of such "fresh from Git" servers is to test the latest unstable branch of the code, not to have a testbed for demonstrating unfinished features. Features should be demonstrated with GUI mock-ups before they are implemented (these can be uploaded to Wikimedia Commons (preferred) or to this wiki), and implementations should only be pushed to Gerrit if they are in a reasonably complete state. This ensures that we avoid features that are never finished. To test your own code, please make sure you have a fully working local MediaWiki installation; if you want others to test your unstable code, you can always set up your own test server.
Documentation policy[edit | edit source]
If a feature is going to be visible to end users or administrators, it's nice if the developer documents the feature on this wiki. Just a few sentences are fine: what it does, how to use it. Others will fix your prose up – the important part is to have features documented. There are various templates available on this wiki using which you just have to edit a few lines and the template will handle everything else. As the developer, you are the subject matter expert and therefore possibly in a better position than anyone else to document the feature accurately and thoroughly, especially if some aspects of it are not particularly self-explanatory. If you're too lazy, on the other hand, there is fortunately at least the theoretical possibility that someone will be willing and able to do it for you, since this is an open-edit wiki.