Writing an extension for deployment

This page documents instructions for writing a MediaWiki extension for deployment on Wikimedia wikis.

Many people, volunteers and Wikimedia Foundation staff alike, have written extensions that have been deployed to Wikimedia sites.

The general workflow is:
 * If you haven't already started working on the code, get a user experience design review first. It is much easier to do the design review before code development begins.
 * Create a Labs account at labsconsole:Special:UserLogin/signup.
 * Submit your code to Gerrit for code quality, security, performance, and internationalization reviews.
 * If all above is okay, file a bug in Bugzilla to get the extension a deployment window, managed by the Wikimedia Foundation Release Manager.

Get Git access
Create a Labs account at labsconsole:Special:UserLogin/signup.

Design review
Whether you have already written the extension or it's just an idea, you'll need a design review.

If your idea is a feature that users will see, it may need a product design review and then a user experience design review.

For a product design review, talk to a Wikimedia Foundation product manager. This starts a conversation (and possibly testing) about the design of your feature, which should include community consensus on the wiki where the extension would be deployed. If the process stalls, forward your note to a product manager who will promise to get this into the biweekly product team discussions.

For user experience design review, e-mail the design mailing list. As you continue the conversation, you should use your judgment on whether to write code as you go, write some prototype code to aid in the discussion, or wait till the conversation's reached some consensus on user experience design.

E-mail the Wikimedia developers' mailing list for a technical design review. (If you don't get a response within a week, ask the Technical Contributor Coordinator for help.) The reviewer will check whether the idea would work with our existing code and architecture. They may point you to another extension that is already in use whose functionality duplicates what you want, or could be easily extended to do what you want. In that case, you should use Git to work on the extension that is already in use.

Code location and internationalization
Extensions that will be deployed should be in Git. Put yours in Git -- see Git/New repositories. With your developer access, you can also set up an instance in Wikimedia Labs for testing and demonstrations.

This gets the ball rolling on a technical level. The extension will need to be translated on Translatewiki before it can be deployed anywhere, and putting it in Git with the proper i18n files and such will make that happen fairly quickly.

It's a good idea to start documenting your extension, at this point, here on MediaWiki.org. The extension template is a good place to start.

Deployability and feature flags
Wikimedia Foundation runs nearly a thousand wikis in hundreds of languages. Even when we deploy code on our cluster, we enable extensions on a wiki-by-wiki basis and often configure them differently for each one. An important feature for an extension is it should have feature flags turning behavior on and off. People will feel a lot more comfortable deploying an extension that does nothing until  is set, and has a separate   flag.

Code review
Continue working on your extension within your Git repository (your Gerrit project). Read Coding conventions, Pre-commit checklist, Performance tuning, and Security for developers and make sure that your code follows these guidelines!

You should try to get two or more trusted developers to follow your project in Gerrit and give you reviews. Find a couple of established MediaWiki hackers to look over your code and point out any flaws in it. If you don't yet know any other MediaWiki developers, ask in IRC, or on the developers' mailing lists. They will help you find anything that doesn't have a chance of making it past the next step. Make sure they know you're trying to follow this guide. If they know you're trying to get your code deployed, they'll look for things that would block deployment.

Review for deployment
After your extension is basically complete, your code has been checked by a few developers and the issues have been resolved, file a bug report in Bugzilla (under Wikimedia → Extension setup) asking that the extension be reviewed by one of the senior MediaWiki developers and deployed by the release manager.

The bug should:
 * point to on-wiki community consensus for having the extension installed on a particular wiki, as necessary; and
 * indicate that the extension hasn't been deployed to a Wikimedia wiki yet and ask for a deployment review.

If you need help with that, poke the Bugwrangler.

Connect it to the extension review tracking bug by saying that your bug blocks bug 31235.

Anything that is deployed on the Wikimedia cluster needs to be reviewed for security and scalability issues. Anyone in the group that owns the MediaWiki Gerrit project can perform a deployment review, so you can ask them directly, or you can ask the Engineering Community Manager to help you find a deployment reviewer. Any issues that the deployment reviewer identifies must be addressed before anyone can deploy your code on the cluster. If you've followed the advice of earlier reviewers closely, you probably won't have too much of a problem here. But the senior developers do their job very seriously, so they may well spot a show-stopper that eluded your earlier reviewers.

Deploy to beta cluster on labs
Before enabling a new extension in production, it should be tested on the Beta cluster. To do this, add the new extension to the mediawiki/extensions.git repo after the above steps. It will be updated automatically. It uses the same wmf-config directory and repository as production. However, there are InitialiseSettings-labs.php and CommonSettings-labs.php files so you can have settings that only apply to Labs. When testing on Labs before production, you will override wgUseNewExtension to true (on one more or more wikis).

It is possible to deploy extensions that do not exist in production to the Beta cluster. However, Beta runs code only from the master branch in git. We suggest merging code to the master branch early and often in order to exercise that code as fully as possible on the beta cluster before it goes out to the general public. For detailed questions about using the beta cluster for testing, see the mail list for Quality Assurance or IRC in #wikimedia-qa

Schedule for deploy
If everything appears ready for deployment, then the deployment reviewer should add the "shell" keyword to the bug (so that people with shell access can find the request), and the release manager should move the deployment request from Review queue to Deployment queue. The current release manager is Greg Grossmeier, but check the canonical release manager page or ask in IRC to confirm.

Benefit
Getting something deployed is not an easy task, but if you can meet the challenge, you know you've done something that not many people are capable of, and you'll improve millions of people's lives.