Writing an extension for deployment
This page documents instructions for writing a MediaWiki extension for deployment on Wikimedia wikis. Many people have written extensions that have been deployed to Wikimedia wikis.
The general workflow is:
- If you haven't already started working on the code, get a user experience design review first.
- 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 task in Phabricator to get the extension a deployment window, managed by the Wikimedia Foundation Release Manager.
- 1 Get community support for your idea
- 2 Get your design reviewed
- 3 Set up your new project for development
- 4 Coding your extension
- 5 Code review
- 6 Review for deployment
- 7 Deploy to beta cluster on Labs
- 8 Schedule deployment
- 9 See also
Get community support for your idea
Community support can be shown by having an active discussion on the need of the extension on a wiki and documenting the responses. If there is no active community support, support can be built through discussions and proposals.
- Post your idea to the wikitech-l mailing list to get feedback from experienced developers and Wikimedians
- Communicate your ideas/plans to affected wikis to garner both support and suggestions/feedback
Get your design reviewed
Whether you have already written the extension or it's just an idea, you'll need a design review before your code is deployed. Chances are good that changes will be needed to your initial design to accommodate the overall product and UI goals as well as the technical realities of running your code on Wikimedia project sites. Changing your design is easier sooner rather than later so start looking for reviewers as soon as you can.
Product 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 can attempt to raise visibility in the biweekly product team discussions.
User experience design review
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.
Technical design review
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.
Set up your new project for development
Once your idea has been vetted by the community and is generally seen as a useful and practical addition, you should set up development within the MediaWiki project.
- Sign up for developer access if you do not already have it.
- Create an
Extension:My Extensionpage in the Extension: namespace on mediawiki.org documenting your extension for developers and for people who will install or configure the extension. The extension template is a good place to start.
- Create a
Help:Extension:My Extensionpage in the
Help:Extension:namespace on mediawiki.org for your extension's end user documentation. Cross-link it with the
Extension:My Extensionpage above.
- Request a project in Phabricator to track bugs and feature requests for your extension. As a member of a project in Phabricator you will be notified of all new bugs reported in the component.
- Request a new Gerrit repository to store the source code for your extension. This is where all code review will happen.
- Find an existing Labs project to join or request a new one to host a testing server with your extension deployed to it for testing and demonstrations.
Coding your extension
The developing extensions page contains a good overview of the parts needed in an extension. Read Coding conventions, Pre-commit checklist, Performance guidelines, and Security for developers and make sure that your code follows these guidelines.
Deployability and feature flags
The Wikimedia Foundation runs nearly a thousand wikis in hundreds of languages. When we deploy code on our cluster, we enable extensions on a wiki-by-wiki basis and often configure them differently for each one.
It is important that extensions have feature flags for turning particular behavior on and off, where that makes sense.
People will feel a lot more comfortable deploying an extension that does nothing until
$wgMyExtensionLoadGun = true is set, and has a separate
$wgMyExtensionPullTrigger = false flag.
See Development policy#Database patches. If your code requires a schema change (e.g. a new column on an existing table) either for core or an extension, keep in mind the schema change may happen only years later.
If at all possible, avoid schema changes.
Compatibility with other deployed extensions
Your extension must be compatible with all extensions deployed on the Wikimedia cluster. Specific issues follow.
- Renameuser and UserMerge
- If your extension has a database table that stores usernames, it needs to respond to the
RenameUserSQLhook to add its tables. If your extension is storing user IDs or usernames, it needs to respond to one or both of the
UserMergeAccountFieldshooks to update its tables accordingly. See hooks.txt.
- If your extension makes edits to pages, you need to consider whether it should do this on Flow boards and Flow topics, and handle them specially. For example, the MassMessage extension can post a message on a Flow-enabled user talk page.
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 developers 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
|It has been suggested that this article or section be merged with Review queue#Checklist. (Discuss)|
After your extension is basically complete, your code has been checked by a few developers and the issues have been resolved create a tracking task in Phabricator. Afterwards, please go to T33235, click "Edit Blocking Tasks" and add the task number that you just created before. This task should only concern deployment itself; any sub-issues (that block deployment) should be separate tasks that are marked as "blocking" this task.
Your deployment tracking 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.
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 Developer Relations team to help you find a deployment reviewer. Track these requests by creating security and performance review bugs and marking them as blocking your deployment tracking bug.
Any issues that the deployment reviewers identify 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 can be tested on the beta cluster. To do this,
- Add the new extension to the mediawiki/extensions.git repo. Thereafter the extensions.git repository will be updated automatically as your extension changes.
- Require and configure the new extension. The beta cluster uses the same wmf-config directory in the operations/mediawiki-config.git repository as production, but in addition the beta cluster machines load
CommonSettings-labs.phpfiles so you can have settings that only apply to Labs. Read more about these config files). When testing on Labs before production, these can override
wgUseMyExtension, setting it to true on one or more beta cluster wikis. (Once your extension is in use in the production wiki(s) corresponding to beta labs, you can probably remove the
It is possible to deploy extensions that do not exist in production to the beta cluster. However, the beta cluster runs code only from the master branch in Git. You should merge code into 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. If you have specific questions about using the beta cluster, you can e-mail the Quality Assurance mailing list or ask in on IRC.