mirror of
https://github.com/NixOS/rfcs.git
synced 2025-11-08 11:36:12 +01:00
e364d5f0cd
* 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>
66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
---
|
|
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 out with the RFC)
|
|
shepherd-team: (names, to be nominated and accepted by RFC steering committee)
|
|
shepherd-leader: (name to be appointed by RFC steering committee)
|
|
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 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.
|
|
|
|
# Drawbacks
|
|
[drawbacks]: #drawbacks
|
|
|
|
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
|
|
|
|
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?
|