From cff592277607e021975eda348991b618d33d66ea Mon Sep 17 00:00:00 2001 From: zimbatm Date: Sat, 18 Mar 2017 21:47:24 +0000 Subject: Implement RFC 0001 (#2) Implement RFC 0001 --- 0000-template.md | 41 +++++++++++++++++++++++++++ README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 121 insertions(+), 6 deletions(-) create mode 100644 0000-template.md diff --git a/0000-template.md b/0000-template.md new file mode 100644 index 0000000..c2c87b7 --- /dev/null +++ b/0000-template.md @@ -0,0 +1,41 @@ +--- +feature: (fill me in with a unique ident, my_awesome_feature) +start-date: (fill me in with today's date, YYYY-MM-DD) +author: (name of the main author) +co-authors: (find a buddy later to help our with the RFC) +related-issues: (will contain links to implementation PRs) +--- + +# Summary +[summary]: #summary + +One paragraph explanation of the feature. + +# Motivation +[motivation]: #motivation + +Why are we doing this? What use cases does it support? What is the expected +outcome? + +# Detailed design +[design]: #detailed-design + +This is the bulk of the RFC. Explain the design in enough detail for somebody +familiar with the ecosystem to understand, and implement. This should get +into specifics and corner-cases, and include examples of how the feature is +used. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? + +# Alternatives +[alternatives]: #alternatives + +What other designs have been considered? What is the impact of not doing this? + +# Unresolved questions +[unresolved]: #unresolved-questions + +What parts of the design are still TBD or unknowns? diff --git a/README.md b/README.md index 1379e7e..ce8f63f 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,88 @@ 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. -The "RFC" (request for comments) process is intended to provide a consistent -and controlled path for new features to enter the language and standard -libraries, so that all stakeholders can be confident about the direction the -ecosystem is evolving in. +This is the bulk of the RFC. Explain the design in enough detail for somebody +familiar with the ecosystem to understand, and implement. This should get +into specifics and corner-cases, and include examples of how the feature is +used. -## TODO +## When this process is followed -The first RFC will define the process around RFCs. +This process is followed when one intends to make "substantial" changes to the +Nix ecosystem. What constitutes a "substantial" change is evolving based on +community norms, but may include the following. + +* Any semantic or syntactic change to the language that is not a bugfix +* Removing language features +* Big restructuring of nixpkgs +* Expansions to the scope of nixpkgs (new arch, major subprojects, ...) +* Introduction of new interfaces or functions + +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 afore mentioned 'substantial' changes may be closed if there is no RFC connected to the proposed changes. + +## Description of the process + +In short, to get a major feature added to the Nix ecosystem, one should first +go through the RFC process in order to improve the likelyhood of inclusion. +Here are roughly the steps that one would take: + +* Fork the RFC repo https://github.com/NixOS/rfcs +* Copy `0000-template.md` to `rfcs/0000-my-feature.md` (where 'my-feature' is + descriptive. don't assign an RFC number yet). +* Fill in the RFC +* Submit a pull request. Rename the rfcs with the PR number. (eg: PR #123 would + be `rfcs/0123-my-feature.md`) + +At this point, the person submitting the RFC should find at least one "co-author" +that will help them bring the RFC to completion. The goal is to improve the +chances that the RFC is both desired and likely to be implemented. + +Once the author is happy with the state of the RFC, they should seek for +wider community review by stating the readyness of the work. Advertisement on +the mailing-list and IRC is an acceptable way of doing that. + +After a number of rounds of review the discussion should settle and a general +consensus should emerge. This bit is left intentionally vague and should be +refined in the future. We don't have a technical commitee so controversial +changes will be rejected by default. + +If a RFC is accepted then authors may implement it and submit the feature as a +pull request to the Nix or nixpkgs repo. An 'accepted' RFC 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. + +Whoever merges the RFC should do the following: + +* 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: +* 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" + +The goal for assigning a "co-author" is to help move the RFC along. + +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 +but should generally be satisfied that the proposed additions are a good thing +for the community. ## License -- cgit v1.2.3