diff options
authorRobin Gloster <>2018-12-25 11:47:01 +0100
committerzimbatm <>2018-12-25 11:47:01 +0100
commitb8b0622bfe5614be2f23494bd65f895d7c0a1d15 (patch)
parent56f5acdb4c5d8422b9bd535eb009f420df16242b (diff)
[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
-rw-r--r--rfcs/0036-review-process.pngbin0 -> 27481 bytes
-rw-r--r--rfcs/0036-rfc-process.pngbin0 -> 38462 bytes
3 files changed, 236 insertions, 0 deletions
diff --git a/rfcs/0036-review-process.png b/rfcs/0036-review-process.png
new file mode 100644
index 0000000..50498ae
--- /dev/null
+++ b/rfcs/0036-review-process.png
Binary files differ
diff --git a/rfcs/ b/rfcs/
new file mode 100644
index 0000000..30eb98b
--- /dev/null
+++ b/rfcs/
@@ -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](, 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]( 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
--- /dev/null
+++ b/rfcs/0036-rfc-process.png
Binary files differ