Requests for comment

The Wikimedia RFC Process is used to facilitate technical decisions or complex changes that are strategic, cross-cutting, and/or hard to undo. Read more about the scope in the TechCom Charter.

Overview

The RFC (Request for comments) process provides a structured workflow for contributors to solicit qualified feedback on a technical proposal. It collects all ideas in one place and it documents whether ideas will be worked on or were discarded, and why.

Note that most changes to Wikimedia software (including MediaWiki), such as bug fixes and enhancements, should not follow the RFC process, but should instead be discussed in the software's issue tracker and/or be submitted as Git patches and follow the normal code review process.

An RFC may be declined if it is believed to be out of the defined scope. If in doubt, consult with TechCom. TechCom members manage the review process and have the authority to approve or decline RFCs.

How to participate

People of all backgrounds and skillsets welcome to provide information during an RFC. This includes Wikimedia users, third-party site admins, bot operators, designers, developers, and more. The rest of this page describe what the focus of the conversation should be at different phases of an RFC.

The RFC conversations take place on Phabricator, our issue tracker. Learn more about commenting on Phabricator.

Ask for help

If you have questions or need help to move to the next phase, you can always ask for help on the task. Other participants might help you get back on track, and TechCom also reviews new comments weekly and will help whenever needed. You can also let other developers know about your RFC or ask for input by e-mailing the Wikitech-l mailing list. Another option is to discuss the RFC with other people during an IRC chat (see RFC review meetings).

Create an RFC

RFCs take the form of a task on the #TechCom-RFC Phabricator workboard.

To create an RFC task, use the Create RFC task template.

Phases

There is no set length of time for a technical RFC.

Phase 1: Define

Under a "Motivation" section, define the problem(s) you are seeking to solve with this RFC, and specify the requirements that proposals should meet.

If the exact scope and requirements are not yet known, it is okay to not yet specify this when creating the task. There are several ways to ask for help.

Once the problem space and desired outcome or acceptance criteria are filled in, the RFC can proceed to Phase 2. To do so, you may move it there on the Phabricator workboard.

Phase 2: Resource

During this phase, the following need to be determined:

Affected components. (Which components benefit from the problem being solved? For example, parts of MediaWiki core, an extension, a service etc. If the scope of the RFC is entirely new and separate from existing Wikimedia software, then specify which components the new service would be used by.)
Software engineer(s) for the initial implementation. (One or more persons, or teams)
Code steward for the code that will be changed or created.

If you're unsure about who the code steward or product owner is for a project, ask for help on the task. A TechCom member, or someone else participating, will help you.

For RFCs that propose a new development policy, the above does not apply; you can lead the writing yourself, if you want to. TechCom is also available to help write the documentation for new policies.

Once the RFC is resourced, the RFC should enter Phase 3. You can move it on the Phabricator workboard.

Phase 3: Explore

In this phase an explicit effort should be made to reach out to hear from stakeholders, engineers, etc. Ask yourself:

Who should be aware of upcoming developments in this area?
Who should be in this conversation that isn't yet?

This is when interested persons should consider the different directions this RFC could take and actively draft proposals. These should be described in the comments on the task. To iterate on longer or more complex proposals, you may want to use a wiki page on mediawiki.org instead (Create a personal sub page, and link your proposal from a comment on the task). Keep the discussion central on the Phabricator task.

Once you have heard from the stakeholders, and have a selected at least one proposal that meets the requirements, the RFC should enter Phase 4. You can move it on the Phabricator workboard.

Phase 4: Tune

This is where you and other participants narrow down which proposal to pursue and make it more concrete. Any concerns that have previously not been explicitly addressed but thought to work out somehow, should be worked out at this point. This is also a good time for stakeholders to confirm that any concerns they raised about the general direction have been accommodated.

Review the proposal(s) against the Architecture Principles and identify any areas that warrant improvement or further discussion.

Once the stakeholder concerns and the Architecture Principles have been addressed, you should indicate which proposal you want to move forward and request a Last Call.

TechCom reviews requests for Last Call weekly and should respond within two weeks. When TechCom has completed their Last Call review and reached a consensus, it will either express any concerns it found, or announce the Last Call.

Phase 5: Last Call

TechCom will ensure that the Last Call status is reflected on the TechCom-RFC workboard and announced in the TechCom Radar.

In this final phase, all stakeholders, current and new participants, have two weeks to introduce new concerns. If no new significant concerns were raised and if no substantive changes were made to the RFC proposal, then TechCom will close the RFC. Otherwise, the RFC may continue in the Tune phase.

To ensure that stakeholders are able to give RFCs the attention they deserve, at most three RFCs may be on Last Call at any given time.