summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorzimbatm <zimbatm@zimbatm.com>2017-03-18 21:47:24 +0000
committerGitHub <noreply@github.com>2017-03-18 21:47:24 +0000
commitcff592277607e021975eda348991b618d33d66ea (patch)
tree1294bcaf9201ab72d0d25df64924d07b8b06d8e3
parent8f83af7ce0f3342bb9d8de21f15dafbaaa1ab4f4 (diff)
Implement RFC 0001 (#2)
Implement RFC 0001
-rw-r--r--0000-template.md41
-rw-r--r--README.md86
2 files changed, 121 insertions, 6 deletions
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