MediaWiki

编写一個部署用的扩展

This page is a translated version of the page Writing an extension for deployment and the translation is 10% complete.
Outdated translations are marked like this.
Languages:

本页將MediaWiki扩展的维护者或代码管理人在扩展有可能被部署之前要讓它通过审查過程，其所需要的步骤，记录到维基媒体的wiki。

任何部署在维基媒体的服务器上的东西都需要审查安全和可伸縮性的问题。 下面有出現「扩展」一词的地方，「皮肤」和「代码」是同义词。

编写一個部署用的扩展可能是一个耗时的项目；我们鼓励任何感兴趣的一方在任何截止日期之前，提早开始这个流程。

你可以查看所有等待审查的扩展列表。

一旦一个扩展通过了审查，那么该扩展就可以由维基媒体基金会发布经理安排部署。

核对表/流程

一般的先决条件和期望

遵循关于写作扩展的一般准则和建议。 阅读编码惯例、提交前检查表、性能指南和Security for developers ，确保你的代码遵循这些指南。

  • WMF stewardship: Find at least one WMF team (or staff member on behalf of their team) to agree to offer basic support for the extension for when it's deployed to Wikimedia Production.[1] Do this step before any other steps. Due to technical debt, WMF capacity to steward extensions is limited.
  • Documentation:
  • 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 become translatable on Translatewiki.net before it can be deployed anywhere. This requires your code to have proper i18n files, etc.
    • Once the extension is deployed on a Wikimedia testing wiki, it should be added to the "Extensions used by Wikimedia - Upcoming" group.
    • Once the extension is deployed on any Wikimedia production wiki, it should be added to one of the other "Extensions used by Wikimedia - *" groups: "Main" for extensions that are used on all wikis, or are otherwise very prominent; "Advanced" for extensions for power users or extensions that work only on some wikis; and so on. API message files and extensions that are only for highly technical people must be in the "Technical" group.
  • 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.
  • Unit testing - Be nice, prepare for sufficient automated testing. Various parts of the code needs different types of testing. In particular check out Manual:PHP单元测试 and Manual:JavaScript unit testing .
  • Database schema - See MediaWiki database policy . 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.
  • Hosting a test version - Toolforge or Cloud VPS 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.
  • Code reviews - You should be closely working with trusted and established MediaWiki developers (ideally, maintainers of core or extensions that have already been deployed to Wikimedia sites) during the entire development and deployment process, in order to ensure that you are familiar with the specific requirements and quirks for writing Wikimedia-deployed code. If you do not have any particular developers in mind, ask in IRC or on the developers' mailing lists . All Wikimedia-deployed extensions and those in the process of becoming deployed must follow the Gerrit/权限方针 .

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 deployment

  1. 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.
  2. 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.
  3. 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.
  4. Request deployment to the Beta叢集 . 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. Having a proper, long-term maintenance plan for the code base that does not rely on individual volunteers has often been a blocker for passing the application security review.[2]
  5. 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.)
  6. 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 #wikimedia-operations 在线) and available during the deployment to respond to any issues that might arise.

This list outlines a broad procedure to follow, including requirements that should be met, but it does not amount to a "process". In particular, the activity of shipping a new extension into production does not have a WMF owner, which can make it tricky to find reviews for related patches. In case of issues, it is recommended to find people (see Gerrit/Code review/Getting reviews#Add reviewers ). Developers are advised that simply opening Phabricator tasks and waiting for someone to pay attention to them is unlikely to be sufficient. See Martin Urbanec's explanation at phab:T61245#9152895.


部署到Beta集群

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.)

流程

  1. 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.
  2. Move your extension's CI config to the "Wikimedia production" section, add the "in-wikimedia-production" job template, and make sure it has and passes all the expected jobs for production code. See example.
  3. 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). See example.
  4. Add your extension to extension-list. See example. This requires that the code be present on every branch running in production, since extension-list is used to build the CDB database for i18n files in both Beta and production.[3]
  5. Add your extension config variable to InitialiseSettings.php and set it to be default false. See example.
  6. Add your extension config variable (same as in previous step) to InitialiseSettings-labs.php and 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.
  7. Load your extension in CommonSettings-labs.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 InitialiseSettings-labs.php and 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 -labs.php overrides.)

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 #wikimedia-releng 在线 on IRC .

Skins follow the same process (but in mediawiki/skins) repository.

After deploying to production

  • Update your Extension:My Extension page on mediawiki.org by adding the {{OnWikimedia}} template.

另见

 
Roan Kattouw's presentation on security.

参考资料

  1. ↑ phab:T355150#9812817
  2. ↑ See, for example, T260466#6530378.
  3. ↑ mailarchive:engineering/2018-March/000520.html
Retrieved from "https://www.mediawiki.org/w/index.php?title=Writing_an_extension_for_deployment/zh&oldid=6907530"