Writing an extension for deployment

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

As you can see from Special:Version, many people have written extensions that then got deployed on Wikimedia sites. Most of those programmers didn't work for the Wikimedia Foundation. In 2011 and 2012 the process had a bottleneck as extensions sat awaiting code review for months at a time, but we're hoping to speed that up by separating the "should WMF sites get this feature?" evaluation step from the "does this code work and perform well?" step.

The general workflow is:
 * If you haven't already started working on the code, get a user experience design review done first. It is much easier to do the design review before code development begins.
 * Create a labs/git/gerrit account at labsconsole:Special:UserLogin/signup
 * Submit your code to gerrit for review.
 * This includes both a security and performance review.
 * Ensure your extension is properly translatable.
 * If all above is OK, file a bug in Bugzilla to get the extension a deployment window, managed by the WMF Release Manager.

More details below....

Get Git access
Create a labs/git/gerrit 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 needs a product design review and then a user experience design review.

For a product design review. Talk to a Wikimedia Foundation product manager. Your first stop is Howie Fung, the director of product management. Tell him your idea and ask whether it's something that Wikimedia Foundation sites should have. This will start 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, your first stop is Jared Zimmerman, creative director. If Jared doesn't respond in about a week, or if the process stalls, forward your note to 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.

If those are done done, or if regular Wikimedia users won't notice the extension, ask the Wikimedia developers' mailing list for an initial technical design review. (If you don't get a response within a week, ask Quim Gil, 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.

This design review phase may take weeks, or even months; we apologize for the slowness. Its aim is to make sure that Wikimedia readers, editors, and contributors have a great user experience, and that the site remains fast and maintainable, and those aren't easy goals!

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;
 * 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.

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. As of August 2013 the release manager is Sam Reed. 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.