Requests for comment

The following is a structured process that may help you suggest and implement a change in MediaWiki that would affect other developers. Apply common sense and good judgment when deciding whether a particular step is applicable or necessary.

You don't need to do this. 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 MediaWiki-RFCs project; also add other Phabricator projects related to the proposal
 * 6) * If your proposal is longer, create a Phabricator task and 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" 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 MediaWiki-RFCs  to the phabricator task if not there already.
 * the Architecture Committee may tag an existing task with #MediaWiki-RFCs, 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 MediaWiki-RFCs 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:
 * Status approved by Tim Starling in 2015-03-04 IRC RFC discussion, requesting some followup (see task comments).

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 #MediaWiki-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 #MW-Rfcs 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 MW-RFCs 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.