This page documents the steps needed to get MediaWiki extensions and other code through the review process before possibly being deployed to Wikimedia wikis. Anything that is deployed on the Wikimedia cluster needs to be reviewed for security and scalability issues.
Writing an extension for deployment can be a time-consuming project; any interested party is encouraged to start the process long before any deadline.
To see all extensions awaiting review, the "Task Graph" list in T33235 links to all yet unreviewed/in-progress extensions.
Once an extension has made it through reviews, then the extension can be scheduled for deployment by the Wikimedia Foundation Release Manager.
General prerequisites and expectations
- General: Follow the general guidelines and recommendations on writing extensions. Read Coding conventions, Pre-commit checklist, Performance guidelines, and Security for developers and make sure that your code follows these guidelines.
- Create an
Extension:My Extensionpage in the Extension: namespace on mediawiki.org to document for developers and people who will install or configure the extension. Use Template:Extension for this.
- 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. Also see Manual:Developing extensions#Help documentation. Example: Help:VisualEditor/User guide. Screencasts can be useful in explaining how things work.
- Create an
- Code hosting: Request a new Git/Gerrit repository to store the source code for your extension. Gerrit is where all code review will happen.
- Issue tracking: Request a project in Phabricator to track bugs and feature requests for your extension. Get notified of new tasks reported in your project.
- Localization: Your extension will need to be translated on translatewiki.net before it can be deployed anywhere. This requires your code to have proper i18n files etc.
- 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. Extensions should have feature flags for turning particular behavior on and off, where that makes sense. We feel more comfortable deploying an extension that does nothing until
$wgMyExtensionLoadGun = trueis set, and has a separate
$wgMyExtensionPullTrigger = falseflag. This enables the extension to be deployed on a subset of wikis (for example, test and test2) without affecting all users.
- Database schema: 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 on the Wikimedia cluster. If at all possible, avoid schema changes.
- Compatibility: Your extension must be compatible with all extensions deployed on the Wikimedia cluster. See #Compatibility with other deployed extensions below for specific issues.
- Hosting a test version: Create a Labs account at labsconsole:Special:UserLogin/signup. Then 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.
- Add your extension to Developers/Maintainers and indicate who the maintainers are.
- Get initial code reviews: Try to get some trusted/established MediaWiki developers to follow your project in Gerrit and to look over your code and point out any flaws in it. If you do not have any particular developers in mind, ask in IRC or on the developers' mailing lists. Tell them you're following this guide so they can look for things that would block deployment.
Once above steps are done, consider getting 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. People 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.
- Communicate your ideas/plans to affected wikis to garner both support and suggestions/feedback.
If you have followed the advice above and the feedback given by early reviewers closely, you probably won't have too much of a problem with the next steps.
Preparing for deployment
- The production deployment tracking task:
- Create a task in Phabricator to get an extension into the review queue. This task should only concern deployment itself. Any issues which block deployment should be separate subtasks (listed under "Task Graph") that block this parent task.
- After creating that task, click "Edit Related Tasks… > Edit Parent Tasks" and add task number T33235.
- Your deployment tracking bug should point to on-wiki community consensus (and/or community support/desire) for having the extension installed on a particular wiki, if applicable.
- Request and incorporate feedback the needed reviews:
- A security review: Open a security review task and mark it as a subtask of the main deployment task
- A product review, if applicable
- A design review, if applicable.
- If you have reasons to think that a database review is needed, create a request in Phabricator.
- Any serious issues identified in these reviews must be addressed before deploying your code.
- After the security review, request deployment to the Beta Cluster (this can aid the other reviews). See #Deploy to Beta Cluster on Labs below for more information.
- Make sure the extension is automatically branched.
- Request a date/time for deployment in the deployment tracking task to get it added to the deployment calendar.
- "You" (the person or persons driving/requesting this) will need to be online (on IRC in ) and available during the deployment to respond to any issues that might arise.
Compatibility with other deployed extensions
As written above, 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.
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 repo. Thereafter the repository will be updated automatically as your extension changes. For example, to add a new extension called RevisionSlider:
git submodule add https://gerrit.wikimedia.org/r/p/mediawiki/extensions/RevisionSlider.git. Once there, extension files are deployed on the beta cluster regardless of defined or not in the configuration.
- Require and configure the new extension. The Beta Cluster uses the same wmf-config directory in the operations/mediawiki-config repository as production, but in addition the Beta Cluster machines load
extension-list-labsfiles 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.
Skins follow the same process (but in mediawiki/skins) repository.
- Review queue tracking bug (under "Task Graph")
- Requests for comment – a place for discussion of large project ideas for MediaWiki
- wikitech:How to deploy code#Case 1d: new extension – details of deploying a new extension on the Wikimedia cluster
- Requesting wiki configuration changes and Limits to configuration changes