User:SPage (WMF)/RFC process


 * ''proposed changes to Requests for comment/Process for T87470

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 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 most good ideas have been considered in the past.
 * 3) Create a subpage of Requests for comment (e.g., "Requests for comment/My thoughtful proposal") on this wiki. Here's an example.
 * 4) * Reference all this "Prior art" in your RFC.
 * 5) 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. If you've socialized the proposed change with key stakeholders ahead of time, discussion will probably be more fruitful.
 * 6) * 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.
 * 7) Discuss your idea over email, 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 on the talk page of your RFC.
 * 8) 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.
 * 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 developers 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
 * they will always accompany these board moves with a comment explaining what's needed: "update RFC to address point XX", etc.

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

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.

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, otherwise documentation can refer to the page.

To address

 * RFC status gets lost between phab and RFC.
 * Which Phabricator states, if any are reflected on-wiki? Can we automate wiki update? If not, we should have wiki state "in ArchCom process" and get rid of many on-wiki states.
 * Where do we log decisions and IRC conversations, on-wiki or in Phab?
 * Must every RFC have a wiki page? Seems not, if 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.