nixos/rfcs
1
0
Fork 0
mirror of https://github.com/NixOS/rfcs.git synced 2025-11-08 19:46:12 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update the RFC process documentation (#150)

Browse source 
* Update the RFC process documentation

- Nudge authors towards using Semantic Line Breaks for writing the RFC text
- Nudge authors towards posting their text as pre-RFC in the forum first
- Tweak wording around who declares FCP slightly
- Make clear that the shepherds have to announce FCP, and when exactly the period officially starts
- Be more open about when to do the implementation work relative to the RFC, and reflect the current practice of starting implementation work early
- Make more clear that RFCs should not be amended, and that important information should live e.g. in documentation instead.

* RFC template: Use semantic line breaks

Given the short text this may not make a huge difference, but given
that every RFC starts with a copy of that template, the hope is that
it will nudge people to continue writing in that style.

* RFC template: Add "Prior art" section

This is mostly inspired by Rust's RFC template.
Also added a couple of words to the "Alternatives" section,
similarly inspired by Rust's template.

* fixup! Update the RFC process documentation

* fixup! Update the RFC process documentation

Co-authored-by: 7c6f434c <7c6f434c@mail.ru>

* fixup! Update the RFC process documentation

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

---------

Co-authored-by: 7c6f434c <7c6f434c@mail.ru>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
This commit is contained in:
piegames 2023-06-13 20:27:23 +02:00 • committed by GitHub
parent 02458c2ecc
commit e364d5f0cd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 71 additions and 56 deletions
Download patch file Download diff file Expand all files Collapse all files

36
0000-template.md
View file

@ -16,35 +16,44 @@ One paragraph explanation of the feature.
# Motivation # Motivation
[motivation]: #motivation [motivation]: #motivation
Why are we doing this? What use cases does it support? What is the expected Why are we doing this? What use cases does it support? What is the expected outcome?
outcome?
# Detailed design # Detailed design
[design]: #detailed-design [design]: #detailed-design
This is the core, normative part of the RFC. Explain the design in enough This is the core, normative part of the RFC.
detail for somebody familiar with the ecosystem to understand, and implement. Explain the design in enough detail for somebody familiar with the ecosystem to understand, and implement.
This should get into specifics and corner-cases. Yet, this section should also This should get into specifics and corner-cases.
be terse, avoiding redundancy even at the cost of clarity. Yet, this section should also be terse, avoiding redundancy even at the cost of clarity.
# Examples and Interactions # Examples and Interactions
[examples-and-interactions]: #examples-and-interactions [examples-and-interactions]: #examples-and-interactions
This section illustrates the detailed design. This section should clarify all This section illustrates the detailed design.
confusion the reader has from the previous sections. It is especially important This section should clarify all confusion the reader has from the previous sections.
to counterbalance the desired terseness of the detailed design; if you feel It is especially important to counterbalance the desired terseness of the detailed design;
your detailed design is rudely short, consider making this section longer if you feel your detailed design is rudely short, consider making this section longer instead.
instead.
# Drawbacks # Drawbacks
[drawbacks]: #drawbacks [drawbacks]: #drawbacks
Why should we *not* do this? What are the disadvantages of doing this?
# Alternatives # Alternatives
[alternatives]: #alternatives [alternatives]: #alternatives
What other designs have been considered? What is the impact of not doing this? What other designs have been considered? What is the impact of not doing this?
For each design decision made, discuss possible alternatives and compare them to the chosen solution.
The reader should be convinced that this is indeed the best possible solution for the problem at hand.
# Prior art
[prior-art]: #prior-art
You are unlikely to be the first one to tackle this problem.
Try to dig up earlier discussions around the topic or prior attempts at improving things.
Summarize, discuss what was good or bad, and compare to the current proposal.
If applicable, have a look at what other projects and communities are doing.
You may also discuss related work here, although some of that might be better located in other sections.
# Unresolved questions # Unresolved questions
[unresolved]: #unresolved-questions [unresolved]: #unresolved-questions
@ -54,5 +63,4 @@ What parts of the design are still TBD or unknowns?
# Future work # Future work
[future]: #future-work [future]: #future-work
What future work, if any, would be implied or impacted by this feature What future work, if any, would be implied or impacted by this feature without being directly part of the work?
without being directly part of the work?

77
README.md
View file

@ -115,44 +115,45 @@ graph TD
0. Have a cool idea! 0. Have a cool idea!
1. Fill in the RFC. Put care into the details: RFCs that do not present 0. Fill in the RFC. Put care into the details: RFCs that do not present
convincing motivation, demonstrate understanding of the impact of the design, convincing motivation, demonstrate understanding of the impact of the design,
or are disingenuous about the drawbacks or alternatives tend to be 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 poorly-received. Consider using [Semantic Line Breaks](https://sembr.org/)
repository to help you flesh it out with a few supporters or chat/video in order to get better diffs on later amendments.
conference with a few people involved in the topic of the RFC. 0. Consider publishing your RFC as pre-RFC [in the forum](https://discourse.nixos.org/c/dev/rfc-steering-committee/33)
2. In case your RFC is a technical proposal, you might want to prepare a to gather initial feedback and iron out the remaining typos.
0. 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 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 and also help reviewers understand the RFC. Code may be able to explain some
issues in short. issues in short.
3. Submit a pull request. As a pull request the RFC will receive design feedback 0. 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 from the larger community, and the author should be prepared to revise it in
response. response.
4. For the nomination process for potential members of the RFC Shepherd Team, 0. For the nomination process for potential members of the RFC Shepherd Team,
that is specific to each RFC, anyone interested can either nominate another 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 person or themselves to be a potential member of the RFC Shepherd Team. This
can already be done when submitting the PR. can already be done when submitting the PR.
5. The RFC Steering Committee assigns a subset of the nominees to the RFC 0. 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 Shepherd Team and designates a leader for it. This has to be done
unanimously. unanimously.
6. Build consensus and integrate feedback. RFCs that have broad support are much 0. 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 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 free to reach out to the RFC Shepherd Team leader in particular to get help
identifying stakeholders and obstacles. identifying stakeholders and obstacles.
7. The RFC Shepherd Team will discuss the RFC pull request, as much as possible 0. 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 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 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 preferable to get to a solution for complex issues, will be summarized on the
pull request comment thread. pull request comment thread.
8. RFCs rarely go through this process unchanged, especially as alternatives and 0. 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 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, 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. and leave a comment on the pull request explaining your changes.
Specifically, do not squash or rebase commits after they are visible on the Specifically, do not squash or rebase commits after they are visible on the
pull request. pull request.
9. At some point, a member of the RFC Shepherd Team will propose a "motion for 0. At some point, a member of the RFC Shepherd Team will propose to start the
final comment period" (FCP), along with a disposition for the RFC (merge or "Final Comment Period" (FCP) on behalf of the team, along with a disposition
close). for the RFC (usually "merge" or "close").
* This step is taken when enough of the tradeoffs have been discussed that * 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 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 require consensus amongst all participants in the RFC thread (which is
@ -165,16 +166,20 @@ graph TD
* For RFCs with lengthy discussion, the motion to FCP is usually preceded by * 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 a summary comment trying to lay out the current state of the discussion
and major tradeoffs/points of disagreement. and major tradeoffs/points of disagreement.
* Before actually entering FCP, all members of the RFC Shepherd Team must * In order to actually enter FCP, it must be made clear that all members of
sign off the motion. the RFC Shepherd Team sign off the motion, e.g. through comments, reactions,
10. The FCP lasts ten calendar days, so that it is open for at least 5 business approving reviews or a meeting protocol.
days. It is also advertised widely, e.g. in NixOS Weekly and through 0. The FCP is advertised widely by the shepherds, most importantly in the relevant
Discourse announcements. This way all stakeholders have a chance to lodge [Discourse announcements category](https://discourse.nixos.org/c/announcements/rfc-announcements/22).
any final objections before a decision is reached. It lasts ten calendar days starting with the Discourse announcement, so that
11. In most cases, the FCP period is quiet, and the RFC is either merged or it is open for at least 5 business days. This way all stakeholders have a
chance to lodge any final objections before a decision is reached.
0. In most cases, the FCP is quiet, and the RFC is either merged or
closed. However, sometimes substantial new arguments or ideas are raised, closed. However, sometimes substantial new arguments or ideas are raised,
the FCP is canceled, and the RFC goes back into development mode. the FCP is canceled, and the RFC goes back into development mode.
12. In case of acceptance, the RFC Steering Committee merges the PR. The feedback during FCP may result in minor adjustments to the RFC, this is
not necessarily a reason to cancel FCP.
0. In case of acceptance, the RFC Steering Committee merges the PR.
Otherwise the RFC's pull request is closed. If no 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 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 gets closed, too. A note is added that is should be proposed again, when the
@ -215,8 +220,11 @@ This RFC is being closed due to lack interest. If enough shepherds are found thi
## The RFC life-cycle ## The RFC life-cycle
Once an RFC is accepted the authors may implement it and submit the feature as a Most RFCs describe changes that eventually need to be implemented, usually in
pull request to the Nix or Nixpkgs repo. Being accepted is not a rubber stamp, form of pull requests against one of the Nix\* repositories. Ideally,
implementations are ready to be merged alongside the RFC when it gets accepted.
Other times, implementation happens only after the RFC gets accepted.
Being accepted is not a rubber stamp,
and in particular still does not mean the feature will ultimately be merged; it 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 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 feature and are amenable to merging it. In general though this means that the
@ -231,17 +239,16 @@ 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 completion: authors should not expect that other project developers will take on
responsibility for implementing their accepted feature. responsibility for implementing their accepted feature.
Minor modifications to accepted RFCs can be done in follow-up pull requests. We RFC documents are intended to be seen as the documentation of a decision and a
strive to write each RFC in a manner that it will reflect the final design of snapshot of a moment in time, rather than a specification-like normative document.
the feature; but the nature of the process means that we cannot expect every Think more of a Matrix Spec Proposal and less like an IETF RFC. Therefore,
merged RFC to actually reflect what the end result will be after implementation. once accepted, RFCs should generally not be substantially changed. Only very
minor changes should be submitted as amendments (via a follow-up pull request).
In general, once accepted, RFCs should not be substantially changed. Only very It is the general expectation that any information intended to be normative and
minor changes should be submitted as amendments. More substantial changes should "outlive" the initial RFC process should live outside of the RFC document, mostly
be new RFCs, with a note added to the original RFC. Exactly what counts as a in documentation and code. These may be subject to change as usual, and of course
"very minor change" is up to the RFC Shepherd Team of the RFC to be amended, to any "substantial" changes will again require a new RFC. Usually there is no need
be decided in cooperation with the RFC Steering Committee. to update the original RFC to keep it up with updates on the implementation.
## Members of the RFC Steering Committee ## Members of the RFC Steering Committee