Requests for comment

The following is a structured process that may help you suggest and implement a change in MediaWiki or Wikimedia software that would affect other engineers responsible for Wikimedia sites. This method helps provide Wikimedia committers important advice when altering Wikimedia-deployed code. As the commit access page (+2) states:"This is a big deal. Your merge could cause Wikipedia or other sites to fail. It could create a security vulnerability that allows attackers to delete or corrupt data, or to gain access to private information. And in the more common case, it could cause technical debt to increase if the code doesn't have tests, is poorly implemented or poorly socialized. You're therefore required to read this entire document and carefully review all the relevant links in it before using +2."You don't need an RFC to modify Wikimedia software. Nearly all MediaWiki software is free and open source, so you can change it any way you want, and if you comply with the license you can publish your modified version.

Making a proposal

 * 1) If you're new to development in MediaWiki and the Wikimedia ecosystem, see how to become a MediaWiki hacker before submitting an RFC. If you consider our principles of general measures of software quality, user experience, testability, respect for user privacy, and support for instrumentation (e.g., logging and analytics) early on, you'll save yourself future rework.
 * 2) Familiarize yourself with similar proposals in RFCs, bug reports, wikitech-l e-mail threads, and other wiki pages. MediaWiki software has been around for over a decade, so many good ideas have been considered in the past.
 * 3) Write up your proposal
 * 4) * If your proposal is only a few paragraphs, submit it as a Phabricator task (help on creating a task)
 * 5) ** the submit link above will add your proposal to the ArchCom-RFC project; also add other Phabricator projects related to the proposal
 * 6) * If your proposal is longer, also create a subpage of Requests for comment (e.g., "Requests for comment/My thoughtful proposal") on this wiki (Here's an example).
 * 7) * Reference all the "prior art" and related tasks in your RFC.
 * 8) Announce the RFC by email on the wikitech-l mailing list and with other stakeholders. Starting the subject line with RFC:  will help people know you're discussing an RFC. Provide a link to your RFC in Phabricator. If you've socialized the proposed change with key stakeholders ahead of time, discussion will probably be more fruitful.
 * 9) * Key stakeholders include the maintainers for the area(s) affected by your proposal, product managers, and people who developed or recently worked on the code in that area (available from `git log` summaries and project commits in gerrit). You can briefly alert them to the existence of your RFC.
 * 10) Discuss your idea over email, in comments on the Phabricator task, on IRC, on your RFC's talk page, and audio/video/in-person. Have an email trail on wikitech-l and link to or archive any offwiki discussion in the Phabricator task.
 * 11) When you've got received some feedback and addressed it, you can formally ask for your RFC to be considered by the Architecture committee (next section)

If you can prototype your proposal quickly, great! That may help people understand your proposal. If you're proposing massive or hard-to-roll back changes, prototyping can still be helpful, but consulting with people on wikitech-l can help you reality check your assumptions before investing lots of your time. If you do have working code,
 * you can submit it to gerrit for easy browsing.
 * It helps to let people try it. If you don't have your own web server, you can request a labs instance to run you modified code.

Architecture committee process
The Architecture committee eventually considers all RFCs. They manage this part of the process in Phabricator.


 * If the RFC does not already have a Phabricator task, create one, and add the task's TNNNNN code to the on-wiki RFC page in the field.
 * add the project tag ArchCom-RFC  to the phabricator task if not there already.
 * the Architecture Committee may tag an existing task with #ArchCom-RFC, with a comment similar to "This needs architectural review. Do not merge until there is an RFC review, see RFC process  ". E.g. T73236
 * track RFC progress on the ArchCom-RFC workboard.
 * The Architecture committee may assign someone to work on the RFC (on the committee or a delegate), shown by assigning it to that person in Phabricator.
 * A developer can move RFC task from the blocked/stalled/draft column to "under discussion" when she believes it's ready for discussion
 * you must always accompany these board moves with a comment "I believe this RFC is ready", "I would like discussion of this in next RFC office hour", etc.
 * ArchCom will often move task back to blocked/stalled/draft column, assigning it to someone
 * they will always accompany these board moves with a comment explaining what's needed: "update RFC to address point XX", etc.
 * Again when you address the issues, say so in a comment and move the task back to "under discussion"

"IRC office hours" public RFC discussion
Unless an RFC is uncontroversial there's usually a need/opportunity for public focused discussion in the IRC office hours  RFC review meeting. If you miss it, IRC bots take notes; see meetbot logs and raw wm-bot logs).

Decision
Prepend the decision (approved or declined), to the task description with a link to the public record (e.g. a meetbot log). Example:
 * approved this in 2015-03-04 IRC RFC discussion, Tim Starling requests some followup (see meeting summary).

Aftermath

 * Look for the decision from the Architecture committee, or an appointed delegate.

After the Architecture committee accepts your RFC, it probably still has to be implemented. A simple RFC can be assigned to someone to implement, a more complex one may be a separate Phabricator task or a set of subtasks of the RFC. These other tasks need not be in the #ArchCom-RfCs project.

Documentation
Often documentation should be updated to reflect the change. You can add the #Documentation tag to the Phabricator task. Sometimes the RFC becomes the documentation page (e.g. the "Guidelines for extracting, publishing and managing libraries" RFC moved to Developing libraries), otherwise documentation can refer to the RFC.

Process issues to consider

 * RFC status gets lost between Phabricator and RFC.
 * Architecture committee think only final state (approved or declined) should be in wiki pages, the rest should be "see Phabricator board for status" (unless we can automate updating the wiki page from Phabricator workboard moves). This means eliminating some wiki states in RFC.
 * Where do we log decisions and IRC conversations, on-wiki or in Phabricator?
 * Mainly Phab. Someone could use   in the wiki page's RFC.
 * Must every RFC have a wiki page?
 * No, since the #ArchCom-RFC project is canonical.
 * Someone can submit a patch for an RFC task that a reviewer +2s, hence it is deployed, regardless of the state of the task on the ArchCom-RFC workboard or the state of the RFC on-wiki.
 * This happened 2015-02 with RFC for Clickable section anchors, it was "in discussion, Seek comment from a designer" since 2013-07.