From db237d502a5afb425cc1532769659485a72b35d8 Mon Sep 17 00:00:00 2001 From: David Arnold Date: Fri, 11 Jun 2021 15:44:55 -0500 Subject: [PATCH] Update Readme with RFC Categories (implied) changes --- README.md | 89 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 892e23595..2257aff21 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ # Nix RFCs (Request For Comments) -Many changes, including bug fixes and documentation improvements can be +Many ideas, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow. -Some changes though are "substantial", and we ask that these be put through a -bit of a design process and produce a consensus among the Nix community. +Some ideas though are "substantial", and we ask that these be put through a +bit of a public process and produce a consensus among the Nix community. ## When this process is followed -This process is followed when one intends to make "substantial" changes to the -Nix ecosystem. What constitutes a "substantial" change is evolving based on +This process is followed when one intends to apply "substantial" ideas to the +Nix ecosystem. What constitutes a "substantial" idea is evolving based on community norms, but may include the following. * Any semantic or syntactic change to the language that is not a bug fix @@ -17,13 +17,23 @@ community norms, but may include the following. * Big restructuring of Nixpkgs * Expansions to the scope of Nixpkgs (new arch, major subprojects, ...) * Introduction of new interfaces or functions +* Making changes to important of formalised community processes +* Record important proof-generated insights that affect the whole community +* Propose an important experiment that affects the whole community +* Document important design issues that affect the whole community +* Start a talk/account/etc. that "officially represents the nix community" Certain changes do not require an RFC: * Adding, updating and removing packages in Nixpkgs * Fixing security updates and bugs that don't break interfaces +* Starting any talk/account/etc. that does not officially represent nix +* Making process changes to (language) sub-systems without being relevant + to the community as a whole +* Conducting experiments, recording insights or documenting design issues in + (language) sub-systems that don't affect the community as a whole. -Pull requests that contain any of the aforementioned 'substantial' changes may +Pull requests that contain any of the aforementioned 'substantial' ideas may be closed if there is no RFC connected to the proposed changes. ## Terminology @@ -73,28 +83,28 @@ 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. +##### RFC Categories +In order to do do justice to the different aspects of documents that merit +generation of broad community consensus via the RFC process, we cassify each +RFC into _feature_, _process_ and _informational_ RFCs. All follow the same +high-level process as described above, but each category requires a different +"mode of discussion", templates, critarias and judgment that it is benefical +to the overall RFC process to identify those categories explicitly. + ## Process from Creation to Merge -*In short, to get a major change included in Nix or Nixpkgs, one must +*In short, to get a major change included in Nix, Nixpkgs or the Ecosystem, one must first get the RFC merged into the RFC repository as a markdown file under the -`rfcs` 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. +corresponding directory. At that point the RFC is accepted and may be implemented +with the goal of eventual inclusion into Nix, Nixpkgs or the Ecosystem.* + +0. Have a cool idea r an important information! +1. Identify its category: _feature_, _process_ or _informational_. +2. Start with the correct template and follow the instructions and comments. 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. + response. Leave them in draft while you're still actively working on them. 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 @@ -152,28 +162,41 @@ with the goal of eventual inclusion into Nix or Nixpkgs.* ![RFC Process](./rfcs/0036-rfc-process.png) ![Review Process](./rfcs/0036-review-process.png) +### Tips + +###### Create Prototypes +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. + +###### Motivation First +In any case, it can be a good idea to elaborate the motivation first, while +leaving the PR in draft. This helps to ensure, that when the solution is +discussed in the future, interested participants can have a clear and refined +picture of the problem that you try to address. ## 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 +Once an RFC is accepted the authors may implement it and for example 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 +about whether a Nix/Nixpkgs community member has been assigned the task of +implementing the RFC. While it is not necessary that the author of the RFC also +does 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 +strive to write each RFC in a manner that it will reflect the final state of +the world; 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