Writing an extension for deployment
This page documents the steps needed for a maintainer or code steward of a MediaWiki extension to get that extension through the review process before the extension is possibly being deployed to Wikimedia wikis. Anything that is deployed on Wikimedia servers needs to be reviewed for security and scalability issues. Where the word "extension" appears below, "skin" or "code" is synonymous.
Writing an extension for deployment can be a time-consuming project; any interested party is encouraged to start the process long before any deadline.
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 expectationsEdit
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. You may use the field below to assist you with it.
- 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. You may use the field below to assist you with it.
- 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.
- Stewardship: Add the project to the Developers/Maintainers page indicating who will be responsible for it's long term stewardship and maintenance.
- 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.
- Gating deployment 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 (e.g.,
wgMaxGeoSearchRadius) for turning particular behavior on and off or configuring some part of the extension, where that makes sense. When extensions are deployed, they will be gated behind a Wikimedia-specific global configuration variable such as
wmgUseEventLogging. This allows the extension to be deployed on a subset of wikis (for example, test and test2) without affecting all wikis. You can search through the existing very large CommonSettings.php and InitialiseSettings.php for reference.
- 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: Cloud VPS projects can be used to host test wikis with your extension installed for testing and demonstrations. See the Cloud Services Getting Started guide for more information.
- Add your extension to Developers/Maintainers and indicate who the maintainers are.
- Get initial code reviews: Try to get some trusted and 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 and plans to affected wikis to garner both support, suggestions, and other feedback.
- To make the below steps easier and faster for the reviewers, you are also encouraged to create a MW-Vagrant role for the extension.
If you have followed the advice above and the feedback given by early reviewers closely, you should have less problems with the next steps.
Preparing for deploymentEdit
- Create a production deployment tracking task within Phabricator (in the #Wikimedia-Extension-setup and #Wikimedia-Extension-Review-Queue projects) 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.
- 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 from the following reviews. These can be included as a "checklist" within the production deployment tracking task's description, (e.g. phab:T190716) or as substasks of the production deployment tracking task. Also note that not every review listed below is a hard requirement for production deployment and that there is no specific order of reviews which need be followed.
- A review from the product owner for the affected area, if applicable. If you are unsure who that might be, it is likely a good idea to reach out to various engineering teams within the Product or Technology verticals for more information and guidance.
- A design review, if applicable.
- A beta feature review, if your extension adds a beta feature.
- A security readiness review: to open a request create a security readiness review task and mark it as a subtask of the production deployment tracking task (via "Edit Task" in the upper right corner). A security readiness review can be a blocker for production deployment depending upon the details of the request and its results.
- A security review for any new external dependencies which should then be added to mediawiki/vendor. Here is a basic list the Security Team typically checks when reviewing third party/vendor code.
- A performance review. This review is typically not a blocker for production deployment.
- If you have reasons to think that a database review is needed, create a request in Phabricator.
- IMPORTANT: Any serious (i.e. blocking) issues identified within the aforementioned reviews must be addressed before any attempt to deploy the code to production is made.
- Request deployment to the Beta Cluster. See #Deploy to Beta Cluster below for more information. While it is strongly recommended to have a security readiness review performed prior to beta cluster deployment, the timing of various project milestones and the nature of the project itself may not accommodate this. In this case, it is best to discuss any proposed beta cluster deployments with the Security Team outside of any requested reviews.
- Make sure the extension is automatically branched by make-wmf-branch.
- IMPORTANT: Not receiving a satisfactory security readiness review is a blocker for this step.
- IMPORTANT: Do this early! Ideally, at least three weeks prior to your target deployment date, to ensure that your extension is present as a submodule in the required branches. (The extension submodule must be present in all branches currently running on the cluster, or the localization cache builder will fail.)
- Request a date/time for deployment in the deployment tracking task to get it added to the deployment calendar.
Compatibility with other deployed extensionsEdit
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.md.
- 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 ClusterEdit
Before enabling a new extension in production, it must be tested on the Beta Cluster. Here are the steps required to deploy and enable a new extension on Beta. (If your extension has more steps/dependencies, say Wikibase, make sure to check with someone before you deploy.)
- Add the new extension submodule to the git mediawiki/extensions repo if it's not already in it. See example. This will result in the code being deployed (unused) to the Beta Cluster.
- Add your extension to the json make-wmf-branch release tool at least two weeks prior to your target date for enabling on the Beta Cluster. It will add the extension as a submodule of mediawiki/core when the weekly deploy branch is cut, and the code will be deployed (unused) to production (see explanation in the next step).
- Add your extension to
extension-list. See example. This requires that the code be present on every branch running in production, since
extension-listis used to build the CDB database for i18n files in both Beta and production. Since the elimination of
extension-list-labsin March 2018, it is no longer possible to enable an extension on the Beta Cluster without first also deploying its code to production.
- Add your extension config variable to
InitialiseSettings.phpand set it to be default false. See example.
- Add your extension config variable (same as in previous step) to
InitialiseSettings-labs.phpand set it to be true on Beta Cluster wikis you want it to be on. You may want to turn it off for loginwiki (which doesn't have most extensions). See example.
- Load your extension in
CommonSettings.php. See example.
The Beta Cluster uses the same wmf-config directory in the operations/mediawiki-config repository as production, but in addition Beta Cluster servers load
CommonSettings-labs.php files so you can have settings that only apply to Beta Cluster. Read more about these config files). When testing on Beta Cluster before production, these can override
wmgUseMyExtension, 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 Cluster, you can probably remove the
The Beta Cluster runs code 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 connect on IRC.
Skins follow the same process (but in mediawiki/skins) repository.
After deploying to productionEdit
- Update your
Extension:My Extensionpage on mediawiki.org by adding the
- Review queue project
- 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