This task proposes using the technical decision making process to govern development policies. Please leave feedback and questions as comments on this task.
Background
Wikimedia development policies are mandatory standards of practice for Wikimedia production software. Before January 2021, development policies were governed by the TechCom RFC process. When the Technical Decision Forum started in January 2021, it took over the responsibilities of TechCom but did not define a process for managing development policies. This task proposes a process to govern development policies as a replacement for the TechCom RFC process.
Guiding questions
- Where do development policies fall in the TDMP's decision matrix and who is owner/responsible party for those policies?
- Where and with whom should someone speak when they have questions about interpreting a policy, and when they face problems they think might warrant a change in policy but want to check before escalating to start a decision process?
Scope
This is a difficult task to scope. It involves issues of technical decision making in general and cross-team collaboration. I have attempted here to propose a system that works within the existing WMF technical decision making structure without requiring significant updates to that process or additional overhead.
About development policies
Development policies on mediawiki.org are defined by Template:Development policy:
This page documents an official Wikimedia development policy. There is no current mechanism to make changes, as the TechCom RFC process is defunct.
Development policies define standards of practice for developing and maintaining Wikimedia software. In contrast to development guidelines, policies describe what developers must do, while guidelines describe what developers generally should do. There can be no deviations from policies, while minor deviations from guidelines, like coding conventions, can often be allowed based on individual circumstances.
Pages that use Template:Development policy on mediawiki.org:
Title | Subject | Page created |
---|---|---|
Development policy | Links to other policies; note about PHP serialization | Feb. 2019 |
Wikimedia services policy | Developing and deploying services | Nov. 2019 |
Wikimedia Engineering Architecture Principles | Principles and requirements for all Wikimedia engineering projects | Sept. 2018 |
Support policy for PHP | Process for changes to PHP support in MediaWiki core and components | Oct. 2019 |
Stable interface policy | Process for defining the parts of MediaWiki core that are considered stable for use by other components | Jan. 2017 |
MediaWiki database policy | Requirements for MediaWiki database queries and schema changes | Dec. 2019 |
Gerrit/Privilege policy | Gerrit rights and responsibilities for MediaWiki core and components, including processes for requesting and revoking privileges | Dec. 2018 |
Proposal
Require new policies and changes to existing policies to go through the technical decision making process. This ensures that all stakeholders have an opportunity to provide input without introducing new channels of communication or structures of technical ownership. The scope of the technical decision making process covers decisions with impact beyond the team making the decision. This scope appropriately covers development policies, which in most cases cannot be clearly owned by a single team.
To adapt the technical decision making process to govern development policies:
- Add a step requiring that new policies and changes to existing policies are announced on wikitech-l.
- Create and use a Development policies tag in Phabricator to track tasks related to development policies.
To document this process, repurpose the Development policy page to describe the process and provide a list of policies.
Update Development policy
Rename page to "Development policies", and replace with this content.
Update Technical decision making
Under 2. Define the problem statement:
Add a new Phabricator task template for changes related to development policies, tagged with Development policies and tech-decision-forum, with this content:
**Request type:** Change the content of an active policy / Propose a new policy / Change the status of a policy ## What **Describe that change you're proposing. Include any existing guidance on the subject.** **What does the future look like if this is achieved? ** **What happens if we do nothing?** ## Why **Identify the value(s) this problem/opportunity provides.**
Under 6. Publish decision record:
Add a step that requires the proposer to announce the change or new policy on wikitech-l.
Update Template:Development policy
Add logic to the template that shows content based on a status variable.
Status | Content |
---|---|
Active policies | This page documents an official Wikimedia development policy. Changes follow the technical decision making process. |
Proposed policies | This page documents a proposed Wikimedia development policy. To provide feedback, see [link to phabricator task]. |
Draft policies | This page is a draft of a new Wikimedia development policy. |
Deprecated policies | This Wikimedia development policy has been deprecated. |
Superseded policies | This Wikimedia development policy has been superseded by [link]. |
Alternatives
Policies are managed by developer consensus
In contrast to policies, development guidelines are managed through developer consensus or decision by a lead developer. The most lightweight option for managing development policies is to use similar language and rely on talk page discussions to establish consensus. However, while this process works well for guidelines, the nature of policies requires a more formal process of gathering input from stakeholders.
Policies are owned by a relevant team or group
Another option is for each policy to be owned by a Wikimedia Foundation team, affiliate team, or volunteer group. The owners would be responsible for monitoring the policy's talk page for change requests, consulting stakeholders, fostering consensus, and publicizing decisions. However, in discussion with stakeholders, we found that the responsibilities and goals of WMF teams do not align clearly with individual policies. In addition, coupling policy governance with WMF organizational structure presents a risk that these responsibilities could be lost due to changes in team structure.
Policies are owned by special interest groups
As a way to mitigate the risk of organizational changes in the previous option, each policy could be governed by a dedicated special interest group (SIG) composed of subject matter experts, stakeholders, and people impacted by the policy. Although a precedent exists on mediawiki.org for establishing SIGs, the effort and authority required to establish and sustain these groups is beyond the scope of this task.
Next steps
- Collect feedback and finalize proposal
- Update Development policy to describe the new process
- Create a Development policies tag in Phabricator
- Update Technical decision making with a new Phabricator task template specifically for decisions related to development policies
- Update Template:Development policy to reflect the new process
- Publicize new process