nixos/rfcs
1
0
Fork 0
mirror of https://github.com/NixOS/rfcs.git synced 2025-11-08 11:36: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
Why are we doing this? What use cases does it support? What is the expected
outcome?
Why are we doing this? What use cases does it support? What is the expected outcome?
# Detailed design
[design]: #detailed-design
This is the core, normative part 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. Yet, this section should also
be terse, avoiding redundancy even at the cost of clarity.
This is the core, normative part 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.
Yet, this section should also be terse, avoiding redundancy even at the cost of clarity.
# Examples and Interactions
[examples-and-interactions]: #examples-and-interactions
This section illustrates the detailed design. This section should clarify all
confusion the reader has from the previous sections. It is especially important
to counterbalance the desired terseness of the detailed design; if you feel
your detailed design is rudely short, consider making this section longer
instead.
This section illustrates the detailed design.
This section should clarify all confusion the reader has from the previous sections.
It is especially important to counterbalance the desired terseness of the detailed design;
if you feel your detailed design is rudely short, consider making this section longer instead.
# Drawbacks
[drawbacks]: #drawbacks
Why should we *not* do this?
What are the disadvantages of doing this?
# Alternatives
[alternatives]: #alternatives
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]: #unresolved-questions
@ -54,5 +63,4 @@ What parts of the design are still TBD or unknowns?
# Future work
[future]: #future-work
What future work, if any, would be implied or impacted by this feature
without being directly part of the work?
What future work, if any, would be implied or impacted by this feature without being directly part of the work?