Update the RFC process documentation #150
Conversation
- 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.
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.
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.
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/improving-our-rfc-process/28552/21 |
README.md
Outdated
| conference with a few people involved in the topic of the RFC. | ||
| 2. In case your RFC is a technical proposal, you might want to prepare a | ||
| poorly-received. Consider using [Semantic Line Breaks](https://sembr.org/) | ||
| in oder to get better diffs on later amendments. |
There was a problem hiding this comment.
We may want to suggest @infinisil's idea (which Guido van Rossum also had some time back) to open a separate development repo for large-scale proposals.
There was a problem hiding this comment.
I think so far RFCs of this scale have been mostly the exception? So not sure if this is applicable advice for the average RFC author.
There was a problem hiding this comment.
Note that there's already an RFC where I proposed this: #138
| "very minor change" is up to the RFC Shepherd Team of the RFC to be amended, to | ||
| be decided in cooperation with the RFC Steering Committee. | ||
|
|
||
| RFC documents are intended to be seen as the documentation of a decision and a |
There was a problem hiding this comment.
As a follow-up, we might want to rename the RFC to ADR or DR to remove the confusion even further.
The document is called an RFC because it's looking to gather comments. Once all the comments have been gathered and integrated, what we have is an (Architecture) Record of Decision.
Splitting those two might allow for more flexibility in the process. This repo becomes a log of record of decision, and the RFC process can potentially happen in a different place.
There was a problem hiding this comment.
I agree that RFC is a pretty bad name (even for its first incarnation IMO), and that projects who pick something "change proposal" or "enhancement proposal" have better names. But what you are suggesting is not a name change but a fundamental new vision of how our process might look like, and therefore requires to have its own RFC discussion.
(As you can see, I'm trying pretty hard on making an incremental improvement to the current situation without getting involved in yet another RFC …)
There was a problem hiding this comment.
Agreed, this is why I wrote: "as a follow-up". It was more of a general remark.
Co-authored-by: 7c6f434c <7c6f434c@mail.ru>
There was a problem hiding this comment.
Thank you for the great editing work!
I seem to be a habitual nitpicker about RFC process as we have it defined; I have read through the changes and I agree they are done very carefully to document the same process (with minor addition of best practices — «prior art» section is indeed often useful and indeed does not change the process).
|
So, what's the process of getting this merged? |
|
@zimbatm you have merge access and no one complained about the change. |
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
thanks! |
* 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>
Changes inspired by https://discourse.nixos.org/t/improving-our-rfc-process/28552/19. Changelog summary in the commit message. I took the opportunity to also update our template a bit.
I expect that these changes should be pretty uncontroversial and not require going through the formal RFC process, as they either clarify the intention in accordance with existing RFCs or make existing conventions explicit. In other words, nothing substantial should change with our process in practice.
There were more points discussed in the discourse thread that I did not manage to fit in: (
The expectations around Shepherds and to which extent they may also be authors.Edit: I don't think it should be mentioned in the RFC process currently, as there seems to be disagreement on some aspects of what teams actually are at the moment. Those should be discussed first.) I also left out any discussions around how to reach consensus around deeply controversial RFCs, because I expect that discussion to require an RFC on its own.On a side note, this repository has two very old feature branches (
import-from-derivationsandrfc-process) which really confused me for a minute. Somebody with permissions please delete them. (CC @zimbatm)