From b8b0622bfe5614be2f23494bd65f895d7c0a1d15 Mon Sep 17 00:00:00 2001 From: Robin Gloster Date: Tue, 25 Dec 2018 11:47:01 +0100 Subject: [RFC 0036] Improving the RFC process (#36) * 0036-rfc-process-team-amendment: draft Co-authored-by: Graham Christensen * 0036-rfc-process-team-amendment: clarifications Co-Authored-By: globin * 0036-rfc-process-team-amendment: remove typo recommendation The github UI has improved since this was written and we should no longer discourage this. * 0036-rfc-process-team-amendment: Glossary -> Terminology * 0036-rfc-process-team-amendment: disallow author/co-author as Shepherds * 0036-rfc-process-team-amendment: incorporate feedback from discussion * 0036-rfc-process-team-amendment: update rfc process graph * 0036-rfc-process-team-amendment: merge postpone and reject * 0036-rfc-process-team-amendment: improve Shepherd Leader paragraph --- rfcs/0036-review-process.png | Bin 0 -> 27481 bytes rfcs/0036-rfc-process-team-amendment.md | 236 ++++++++++++++++++++++++++++++++ rfcs/0036-rfc-process.png | Bin 0 -> 38462 bytes 3 files changed, 236 insertions(+) create mode 100644 rfcs/0036-review-process.png create mode 100644 rfcs/0036-rfc-process-team-amendment.md create mode 100644 rfcs/0036-rfc-process.png diff --git a/rfcs/0036-review-process.png b/rfcs/0036-review-process.png new file mode 100644 index 0000000..50498ae Binary files /dev/null and b/rfcs/0036-review-process.png differ diff --git a/rfcs/0036-rfc-process-team-amendment.md b/rfcs/0036-rfc-process-team-amendment.md new file mode 100644 index 0000000..30eb98b --- /dev/null +++ b/rfcs/0036-rfc-process-team-amendment.md @@ -0,0 +1,236 @@ +--- +feature: rfc-process-team-amendment +start-date: 2018-10-27 +author: Robin Gloster +co-authors: Graham Christensen +related-issues: 1 (initial process), 24 (implementation) +--- + +# Summary +[summary]: #summary + +This RFC proposes an RFC Steering Committee who decide on a group of RFC +shepherds for each RFC who guide the discussion to a general consensus and then +propose a motion for a "Final Comment Period" (FCP) with a disposition for +acception or rejection (see Terminology for a short definition) + + +# Motivation +[motivation]: #motivation + +A lot of RFCs have stalled and already an [RFC has been submitted exactly on +this topic](https://github.com/NixOS/rfcs/pull/18), which ironically has not +been decided on either. This new RFC takes the above into account and tries to +expand on that to flesh out the process further. During this effort a lot of +inspiration has been taken from [Rust's RFC +process](https://github.com/rust-lang/rfcs#what-the-process-is) which works well +and we have adapted to our needs. + + +# Detailed design +[design]: #detailed-design + +## Terminology + +##### RFC Steering Committee +A team of people defined by _this_ RFC and stays consistent until the team +members are changed via a follow-up RFC. This committee is responsible for +forming an RFC Shepherd team from the available nominations on each RFC. This +team also names the leader of the Shepherd team. This has to happen within 1 +week after the PR has been opened. Until then the Steering Committee is +responsible for guiding the discussion. In case of the Shepherding Team not +doing its work the Steering Committee shall encourage them or step in and assign +new Shepherds. They also are in charge of merging accepted and rejected RFCs. +Generally by these expectations they should find time to meet once a week for +about an hour. + +They have no special responsibility with regard to the content of an RFC, they +can weigh in on them, the same as any other community member, but are only in +charge of: + * selecting the Shepherds unanimously + * supervising that the Shepherds are carrying out their work + * committing the final RFC + +##### Shepherd Team +A team of 3-4 community members defined unanimously by the RFC Steering +Committee, responsible for accepting or rejecting a specific RFC. This team is +created per RFC from community members nominated in the discussion on that RFC. + +This team should be people who are very familiar with the main components +touched by the RFC. The author cannot be part of the Shepherd Team. In addition, +at most half of the Shepherd Team can be part of the RFC Steering Committee. + +The resposibility of the team is to guide the discussion as long as it is +constructive, new points are brought up and the RFC is iterated on and from time +to time summarise the current state of discussion. If this is the case no longer, +then the Shepherd Team shall step in with a motion for FCP. + +##### Shepherd Leader +The person in charge of the RFC process for a specific RFC, and responsible for +ensuring the process is followed in a timely fashion. The Shepherd Leader has no +special resposibility with regard to moving an undecided Shepherd Team to a +certain decision. + +##### Final Comment Period (FCP) +A period of ten calendar days, which will be called by the Shepherd Team after +the RFC has received ample discussion and enough of the tradeoffs have been +discussed. The Shepherd Team will propose to either accept or reject the RFC +after the FCP. + + +## Process from Creation to Merge + +*In short, to get a major change included in Nix or nixpkgs, one must +first get the RFC merged into the RFC repository as a markdown file under the +`accepted` directory. At that point the RFC is accepted and may be implemented +with the goal of eventual inclusion into Nix or nixpkgs.* + +0. Have a cool idea! +1. Fill in the RFC. Put care into the details: RFCs that do not present + convincing motivation, demonstrate understanding of the impact of the design, + or are disingenuous about the drawbacks or alternatives tend to be + poorly-received. You might want to create a PR in your fork of the RFCs + repository to help you flesh it out with a few supporters or chat/video + conference with a few people involved in the topic of the RFC. +2. In case your RFC is a technical proposal, you might want to prepare a + prototype of your idea to firstly make yourself aware of potential pitfalls + and also help reviewers understand the RFC. Code may be able to explain some + issues in short. +3. Submit a pull request. As a pull request the RFC will receive design feedback + from the larger community, and the author should be prepared to revise it in + response. +4. For the nomination process for potential members of the RFC Shepherd Team, + that is specific to each RFC, anyone interested can either nominate another + person or themselves to be a potential member of the RFC Shepherd Team. This + can already be done when submitting the PR. +5. The RFC Steering Committee assigns a subset of the nominees to the RFC + Shepherd Team and designates a leader for it. This has to be done + unanimously. +6. Build consensus and integrate feedback. RFCs that have broad support are much + more likely to make progress than those that don't receive any comments. Feel + free to reach out to the RFC Shepherd Team leader in particular to get help + identifying stakeholders and obstacles. +7. The RFC Shepherd Team will discuss the RFC pull request, as much as possible + in the comment thread of the pull request itself. Discussion outside of the + pull request, either offline or in a video conference, that might be + preferable to get to a solution for complex issues, will be summarized on the + pull request comment thread. +8. RFCs rarely go through this process unchanged, especially as alternatives and + drawbacks are shown. You can make edits, big and small, to the RFC to clarify + or change the design, but make changes as new commits to the pull request, + and leave a comment on the pull request explaining your changes. + Specifically, do not squash or rebase commits after they are visible on the + pull request. +9. At some point, a member of the RFC Shepherd Team will propose a "motion for + final comment period" (FCP), along with a disposition for the RFC (merge or + close). + * This step is taken when enough of the tradeoffs have been discussed that + the RFC Shepherd Team is in a position to make a decision. That does not + require consensus amongst all participants in the RFC thread (which is + usually impossible). However, the argument supporting the disposition on + the RFC needs to have already been clearly articulated, and there should + not be a strong consensus against that position outside of the RFC + Shepherd Team. RFC Shepherd Team members use their best judgment in taking + this step, and the FCP itself ensures there is ample time and notification + for stakeholders to push back if it is made prematurely. + * For RFCs with lengthy discussion, the motion to FCP is usually preceded by + a summary comment trying to lay out the current state of the discussion + and major tradeoffs/points of disagreement. + * Before actually entering FCP, all members of the RFC Shepherd Team must + sign off the motion. +10. The FCP lasts ten calendar days, so that it is open for at least 5 business + days. It is also advertised widely, e.g. in NixOS Weekly and through + Discourse announcements. This way all stakeholders have a chance to lodge + any final objections before a decision is reached. +11. In most cases, the FCP period is quiet, and the RFC is either merged or + closed. However, sometimes substantial new arguments or ideas are raised, + the FCP is canceled, and the RFC goes back into development mode. +12. In case of acceptance, the RFC Steering Committee merges the PR into the + `accepted` directory. Otherwise the RFC's pull request is closed. If no + consensus can be reached on the RFC but the idea in general is accepted, it + gets closed, too. A note is added that is should be proposed again, when the + circumstances, that are stopping the discussion to come to another decision, + change. + + +![RFC Process](./0036-rfc-process.png) +![Review Process](./0036-review-process.png) + + +## The RFC life-cycle + +Once an RFC is accepted the authors may implement it and submit the feature as a +pull request to the Nix or nixpkgs repo. Being accepted is not a rubber stamp, +and in particular still does not mean the feature will ultimately be merged; it +does mean that in principle all the major stakeholders have agreed to the +feature and are amenable to merging it. In general though this means that the +implementation will be merged as long as there are no substantial technical +objections to the implementation. + +Furthermore, the fact that a given RFC has been accepted implies nothing about +what priority is assigned to its implementation, nor does it imply anything +about whether a Nix/nixpkgs developer has been assigned the task of implementing +the feature. While it is not necessary that the author of the RFC also write the +implementation, it is by far the most effective way to see an RFC through to +completion: authors should not expect that other project developers will take on +responsibility for implementing their accepted feature. + +Minor modifications to accepted RFCs can be done in follow-up pull requests. We +strive to write each RFC in a manner that it will reflect the final design of +the feature; but the nature of the process means that we cannot expect every +merged RFC to actually reflect what the end result will be after implementation. + +In general, once accepted, RFCs should not be substantially changed. Only very +minor changes should be submitted as amendments. More substantial changes should +be new RFCs, with a note added to the original RFC. Exactly what counts as a +"very minor change" is up to the RFC Shepherd Team of the RFC to be amended, to +be decided in cooperation with the RFC Steering Committee. + + +## Members of the RFC Steering Committee + +In cooperation and discussion with Eelco Dolstra and all nominees the proposal +for the first iteration of members of the RFC Steering Committee are: + + - Eelco Dolstra (edolstra, niksnut) + - Shea Levy (shlevy) + - Domen Kožar (domenkozar) + - Jörg Thalheim (Mic92) + - Robin Gloster (globin) + + +# Drawbacks +[drawbacks]: #drawbacks + +If the Steering Committee were too biased, it might select a biased Shepherding +Team. We are hoping for them and believe them to commit to doing their work in +the interest of the community. Also this RFC introduces more process and +bureaucracy, and requires more meetings for some core Nix/nixpkgs contributors. +Precious time and energy will need to be devoted to discussions. + +# Alternatives +[alternatives]: #alternatives + +The current state, which hardly ever results in an RFC being accepted. + +A possibility could also be to define owners for particular domains who have the +responsibility of deciding to accept changes in that area. An extreme example of +this case is a BDFL responsible for all final decisions. This would mirror the +model of decisions in the kernel development. Although a soft form of "code +owners" could be the base of decisions for Shepherd nominees for different RFCs, +similar to the Rust RFC model having subteams, to whom RFCs are assigned. + +# Unresolved questions +[unresolved]: #unresolved-questions + +None, as of now. + +# Future work +[future]: #future-work + +Work on auto-labeling RFCs and automation of parts of the process that either do +not need human intervention or to remind people to continue their work. + +Define how the Steering Committee is picked in the future and how to replace +members thereof if they are not able to participate in the meetings, including +guidelines on when to replace members. (a timeline, not being active, etc.) diff --git a/rfcs/0036-rfc-process.png b/rfcs/0036-rfc-process.png new file mode 100644 index 0000000..a27d85f Binary files /dev/null and b/rfcs/0036-rfc-process.png differ -- cgit v1.2.3