Implementation of RFC 36 (#38)

* Implementation of RFC 36

see #36

* Fix reference to 'this RFC' -> RFC #36

README.md

@@ -28,66 +28,176 @@ Certain changes do not require an RFC:
 * Adding, updating and removing packages in Nixpkgs
 * Fixing security updates and bugs that don't break interfaces
 
-Pull requests that contain any of the aforementioned 'substantial' changes may be closed if there is no RFC connected to the proposed changes.
+Pull requests that contain any of the aforementioned 'substantial' changes may
+be closed if there is no RFC connected to the proposed changes.
 
-## Description of the process
+## Terminology
 
-In short, to get a major feature added to the Nix ecosystem, one should first
+##### RFC Steering Committee
-go through the RFC process in order to improve the likelihood of inclusion.
+A team of people defined by [RFC 36](./rfcs/0036-rfc-process-team-amendment.md)
-Here are roughly the steps that one would take:
+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.
 
-* Fork the RFC repository https://github.com/NixOS/rfcs
+They have no special responsibility with regard to the content of an RFC, they
-* Copy `0000-template.md` to `rfcs/0000-my-feature.md` (where 'my-feature' is
+can weigh in on them, the same as any other community member, but are only in
-  descriptive. don't assign an RFC number yet).
+charge of:
-* Fill in the RFC
+ * selecting the Shepherds unanimously
-* Submit a pull request. Rename the RFC with the PR number. (eg: PR #123 would
+ * supervising that the Shepherds are carrying out their work
-  be `rfcs/0123-my-feature.md`)
+ * committing the final RFC
 
-At this point, the person submitting the RFC should find at least one "co-author"
+##### Shepherd Team
-that will help them bring the RFC to completion. The goal is to improve the
+A team of 3-4 community members defined unanimously by the RFC Steering
-chances that the RFC is both desired and likely to be implemented.
+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.
 
-Once the author is happy with the state of the RFC, they should seek for
+This team should be people who are very familiar with the main components
-wider community review by stating the readiness of the work. Advertisement on
+touched by the RFC. The author cannot be part of the Shepherd Team. In addition,
-the mailing-list and IRC is an acceptable way of doing that.
+at most half of the Shepherd Team can be part of the RFC Steering Committee.
 
-After a number of rounds of review the discussion should settle and a general
+The resposibility of the team is to guide the discussion as long as it is
-consensus should emerge. This bit is left intentionally vague and should be
+constructive, new points are brought up and the RFC is iterated on and from time
-refined in the future. We don't have a technical committee so controversial
+to time summarise the current state of discussion. If this is the case no longer,
-changes will be rejected by default.
+then the Shepherd Team shall step in with a motion for FCP.
 
-If a RFC is accepted then authors may implement it and submit the feature as a
+##### Shepherd Leader
-pull request to the Nix or Nixpkgs repository. An 'accepted' RFC is not a rubber
+The person in charge of the RFC process for a specific RFC, and responsible for
-stamp, and in particular still does not mean the feature will ultimately be
+ensuring the process is followed in a timely fashion. The Shepherd Leader has no
-merged; it does mean that in principle all the major stakeholders have agreed
+special resposibility with regard to moving an undecided Shepherd Team to a
-to the feature and are amenable to merging it.
+certain decision.
 
-Whoever merges the RFC should do the following:
+##### 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.
 
-* Fill in the remaining metadata in the RFC header, including links for the
-  original pull request(s) and the newly created issue.
-* Commit everything.
 
-If a RFC is rejected, whoever merges the RFC should do the following:
+## Process from Creation to Merge
-* Move the RFC to the rejected folder
-* Fill in the remaining metadata in the RFC header, including links for the
-  original pull request(s) and the newly created issue.
-* Include a summary reason for the rejection
-* Commit everything
 
-## Role of the "co-author"
+*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.*
 
-The goal for assigning a "co-author" is to help move the RFC along.
+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.
 
-The co-author should:
-* be available for discussion with the main author
-* respond to inquiries in a timely manner
-* help with fixing minor issues like typos so community discussion can stay
-  on design issues
 
-The co-author doesn't necessarily have to agree with all the points of the RFC
+![RFC Process](./rfcs/0036-rfc-process.png)
-but should generally be satisfied that the proposed additions are a good thing
+![Review Process](./rfcs/0036-review-process.png)
-for the community.
+
+
+## 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
+
+The current 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)
+
 
 ## License
 

rfcs/0036-rfc-process-team-amendment.md

@@ -3,7 +3,7 @@ feature: rfc-process-team-amendment
 start-date: 2018-10-27
 author: Robin Gloster <mail@glob.in>
 co-authors: Graham Christensen <graham@grahamc.com>
-related-issues: 1 (initial process), 24 (implementation)
+related-issues: 1 (initial process), 38 (implementation)
 ---
 
 # Summary