RFC to describe the RFC process #1
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| - Feature Name: rfc-process | ||
| - Start Date: 2017-02-12 | ||
| - Authors: zimbatm, ??? | ||
| - RFC PR: | ||
| - Related Issue: | ||
|
|
||
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| The "RFC" (request for comments) process is intended to provide a consistent | ||
| and controlled path for new features to enter the nix language, packages and | ||
| OS, so that all stakeholders can be confident about the direction the | ||
| ecosystem is evolving in. | ||
|
|
||
| # Motivation | ||
| [motivation]: #motivation | ||
|
|
||
| There are a number of changes that are significant enough that they could | ||
| benefit from wider community consensus before being implemented. Either | ||
| because they introduce new concepts, big changes or are controversial enough | ||
| that not everybody will agree on the direction to take. | ||
|
There was a problem hiding this comment. Therefore, the purpose of this RFC is ... |
||
|
|
||
| # Detailed design | ||
| [design]: #detailed-design | ||
|
|
||
| Many changes, including bug fixes and documentation improvements can be | ||
| 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 and | ||
| the core team. | ||
|
There was a problem hiding this comment. Does the distinction between the community and a "core team" makes sense for nix ? There was a problem hiding this comment. Probably not. We have a "core team" but the notion is a bit fuzzy and probably changes from person to person. Removed in 48e3cef |
||
|
|
||
| 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. | ||
|
|
||
| ## When you need to follow this process | ||
|
There was a problem hiding this comment. |
||
|
|
||
| You need to follow this process if you intend to make "substantial" changes to | ||
| the Nix ecosystem. What constitutes a "substantial" change is evolving based | ||
| on community norms, but may include the following. | ||
|
There was a problem hiding this comment. nit: This should as well include making a RFC to describe the processes by which the community interact around the projects. |
||
|
|
||
| - Any semantic or syntactic change to the language that is not a bugfix. | ||
|
There was a problem hiding this comment. style nit: remove trailing period for consistency There was a problem hiding this comment. thanks, fixed as part of 983dca3 |
||
| - Removing language features | ||
| - Big restructuring of nixpkgs | ||
| - Expansions to the scope of nixpkgs (new arch, major subprojects, ...) | ||
| - Introduction of new interfaces or functions | ||
| - A controversial change | ||
|
There was a problem hiding this comment. Also, anything that expands the scope of the project in a significant way. This includes adding support for new platforms or adding major subprojects (think NixUP, nix-make, ...). Really, anything that has the potential of inflicting a lot of crosscutting technical debt or maintenance cost. There was a problem hiding this comment. Also, adding new package abstractions or idioms (think various auto-updaters, Of course, we should probably also better document what the standard style is :-) |
||
|
|
||
| Some changes do not require an RFC: | ||
|
|
||
|
|
||
| - Adding, updating and removing packages in nixpkgs | ||
| - Fixing security updates and bugs that don't break interfaces | ||
|
|
||
| If you submit a pull request to implement a new feature without going | ||
|
There was a problem hiding this comment. Pull requests that contain any of the afore mentioned 'substantial' changes may be closed if there is no RFC connected to the proposed changes. |
||
| through the RFC process, it may be closed with a polite request to | ||
| submit an RFC first. | ||
|
|
||
| ## What the process is | ||
|
|
||
|
|
||
| In short, to get a major feature added to the Nix ecosystem, one should first | ||
| go throught the RFC process in order to improve the likelyhood of inclusion. | ||
|
There was a problem hiding this comment. Is the purpose just to improve the likelihood of inclusion? I think there are other reasons. In any case, this is not the place to mention the reasons again (although I do understand why you pick something here). |
||
| 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 | ||
|
There was a problem hiding this comment. It's in #2 for now. I thought it would make sense to have the implementation separate. |
||
| 'my-feature' is descriptive. don't assign an RFC number yet). | ||
| * Fill in the RFC | ||
| * Submit a pull request. The pull request is the time to get review of | ||
| the design from the larger community. | ||
| * 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. | ||
|
|
||
| At this point, the person submitting the RFC should find at least one "buddy" | ||
|
There was a problem hiding this comment. I'd go even further and find a "shepherd" who has the implied right to pull in people who are currently blocking progress. I don't mean "blocking" in a bad way. AFAICT all PRs die due to indifference or lack of time, not because anyone is maliciously blocking. My hope is that "ownership" will help avoiding no-one being responsible for moving things forward to either accepted or rejected. There was a problem hiding this comment. Yes that's what the Rust community is also using: https://github.com/rust-lang/rfcs#the-role-of-the-shepherd . I think it implies some form of structure like sub-teams and such which is why I didn't go with this, the nix community structure is much more amorphous. In my mind the "buddy" plays a similar role but depends on it's gravity, kudos, community credits, to make things happen. There was a problem hiding this comment. So is it OK to create a PR first, and then find a buddy (by e.g. sending an email to the list)? There was a problem hiding this comment. I don't really understand the exact role of the buddy in our case. For the rust community it makes sense because of the structure of the project (the shepherd belongs to Rust's development team which is a well-defined subset of the community), but as nix community is far less structured, it seems to me that the person submitting the RFC will de facto be his own buddy There was a problem hiding this comment. Maybe "co-author" is more accurate? The goal is multifold. I believe that having someone with whom the author can work more closely with would help to advance the RFC. If the author is not embedded in community, the co-author can lend some credence to the proposal. He can also help respond to other people's question as he hopefully shares enough context with the author. And also help out weed the usually typos and just provide a quicker iteration speed in general. Ideally the author and "buddy" would have a closer relationship, maybe over IRC, voice or video. There was a problem hiding this comment. "peer", "co-author", "contradictor", "guide", "mentor", "buddy", ... I think "buddy" is not formal enough, and confusing as well. I think we need a better name, and a better bullet-list description of what these persons are responsible for, and what they are not responsible for:
There was a problem hiding this comment. Renamed buddy to co-author in 2d315c6. I agree that it would be nice to refine the co-author's responsibilities but it's another thing to reach consensus on. Would it be alright to leave it ambiguous for now? |
||
| that will help them bring the RFC to reality. The goal is to improve the | ||
| chances that the RFC is both desired and likely to be implemented. | ||
|
|
||
| Whomever merges the RFC should do the following: | ||
|
There was a problem hiding this comment. Since this person is the subject of the verb, I think it is Whoever. There was a problem hiding this comment. Thanks, I'll trust you on that 1eb8a17 |
||
|
|
||
| * Assign an id, using the PR number of the RFC pull request. (If the RFC | ||
| has multiple pull requests associated with it, choose one PR number, | ||
| preferably the minimal one.) | ||
|
There was a problem hiding this comment. If it is going to be numbered after the PR, maybe this can be done by the original author, as the PR number is fixed once the PR is submitted. Thus instead of leaving that to the person who merges it, it can be fixed up by the authors. * Copy `0000-template.md` to `rfcs/0000-my-feature.md`There was a problem hiding this comment. Good point. Fixed in b3db396 There was a problem hiding this comment. Ok that's the reason why the RFC needs to be either renamed at the very start or very end: otherwise all the existing comments are being hidden by github. This will be part of the CONTRIBUTING.md or PULL_REQUEST.md so users do the right thing. |
||
| * Add the file in the `rfcs/` directory. | ||
| * Create a corresponding issue on the appropriate repo (NixOS/nix, NixOS/nixpkgs, ...). | ||
| * Fill in the remaining metadata in the RFC header, including links for | ||
| the original pull request(s) and the newly created issue. | ||
| * Commit everything. | ||
|
|
||
| Once an RFC becomes active then authors may implement it and submit the | ||
|
There was a problem hiding this comment. Many changes won't probably drain an unconditional approval from everyone in the community − see the everlasting discussion about the wiki for example ;). It should be useful to have a well-defined notion of when a RFC is accepted for cases where it is not obvious ( Sufficient consensus between a few selected members of the community ? Vote ? Call for @edolstra's decision ?) There was a problem hiding this comment. Totally agreed. One of the reason for going though the RFC process is to avoid everlasting PRs that don't get consensus. The idea is that the RFC will allow to expose the underlying problem and thinking without getting drowned in implementation details. But we could have a similar issue on the RFC submission for sure. As usual @edolstra is the BDFL. Because of the concurrency limit, hopefully RFCs will be quicker for him to evaluate and take an executive decision. I don't have a perfect answer for that as it's a human problem. Some people want perfect solutions while others are willing to accept a compromise as long as the proposed approach improves on what we have already. There was a problem hiding this comment. Should we include this sentence? One could always make an implementation and open a PR. I suppose we might want to write here what our preference is regarding where the discussion takes place. There was a problem hiding this comment. Yeah feel free to suggest better wording for this sentence. There was a problem hiding this comment. I replaced 'active' with 'accepted' which should make things a bit clearer |
||
| feature as a pull request to the nix or nixpkgs repo. An 'active' 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. | ||
|
|
||
|
There was a problem hiding this comment. This needs some more info about the lifecycle. See e.g. https://www.python.org/dev/peps/pep-0001/. For example, what's the status of a finalized RFC? Once PEPs reach "final" state, they're no longer modified and are mostly of historic interest - they're not primary documentation because any relevant doc changes should be made to the manual. This is in contrast to IETF Standards Track RFCs which are primary documentation. There was a problem hiding this comment. I don't really know what's the best solution. I agree that RFCs shouldn't have to be updated but things might come up during the implementation that might trigger another round of discussion. There was a problem hiding this comment. What about having the following state machine: If a RFC has been accepted, but not implemented yet, we could start revising it if there are issues that need RFC level discussions. There was a problem hiding this comment. Most of the value of the RFC is derived from having developers being forced to serialise their thoughts to human language instead of code. It's mainly a communication tool. Unless the RFC gets largely discarded when faced with implementation realities it doesn't need to be amended after merge. RFCs should probably be updated with the relevant implementation PRs for developer to be able to follow the process. There was a problem hiding this comment. I think revision after implementation is more important than before. Everybody always has a favorite bikeshed color, so it's a real pain when you reach a consensus after weeks of discussion only to find that what you need to build isn't a bikeshed at all! To put it less colorfully, there needs to be space to experiment, especially when it comes to changes that affect a wide section of our project. There are always unknowns, and there are always unknown-unknowns. It's important to get feedback from people who are actually using an implementation before setting that implementation in stone. Projects that insist on one-way innovation with no room for experimentation end up strangling themselves with bad decisions that seemed ingenious at the time. The core Haskell projects are a great example of this. If you can't fix a severe security vulnerability without a multi-year deprecation period, something has gone horribly wrong! I'm not suggesting that this proposal is rushing down that path, but I think there should explicitly be room for experimentation in the proposal lifecycle. Leaving room explicitly is why C4 has a "draft" status for public contracts. I'm thinking along these lines: The Well, I wanted to give my two cents, but it looks like I dropped a buck-fifty on the table; sorry about that! There was a problem hiding this comment. No worries :) How I see it, the RFC process is more about doing a project proposal. Right now our de-facto "project manager", the person who can make wide decisions is Eelco, and he doesn't have time to extract meaning from reading code on large pull-requests. The goal here is to push some of that decision-making upfront, before all the work is done. It's more costly to the developer but should help Eelco. It doesn't mean that everything has to be decided upfront though. I agree that we want to avoid doing waterfall design. If that's not clear from the existing wording then it should be revised. Maybe "RFC" is a bad term because it's too close to IETF RFCs. How about I rename them to NIP (Nix Improvement Proposals)? I think that was @moretea's idea. (danger: bikeshed ahead :) There was a problem hiding this comment. Ok, I thought that a graphviz document, with comment would be easier to follow. There is one thing which remains to be determine in the following, which is the set of person responsible for accepting or rejecting proposals. digraph rfc-state {
/* Draft stage, any newly create RFC is in a draft stage. Provide draft implementation for the project, such as
* Nix, Nixpkgs without adding pull request to other repository, but refer to the draft-ed implementation in forked
* version of the projects. */
draft;
/* Submitted stage, a comity of persons (to be defined) evaluates the feasibility and compare benefits against the
* drawbacks. Ideally the peers (buddy, mentors, ...) should have help clear-up the ground for any questions that
* might be asked by the comity. */
submitted;
/* Accepted stage, a comity of persons, agreed with the feasibility and that benefit outweigh the drawback and that a
* complete implementation would be implemented in the projects. */
accepted;
/* Rejected stage, a comity of persons, disagree with the feasibility and/or that the drawbacks outweigh the benefit.
* The comity should provide a comments explaining the choice. Any reject draft should not be submitted until all
* comments are addressed, and not within a period of 3 months (in order to prevent recurrent submissions) */
rejected;
/* Abandoned stage, nor the authors nor the peers (buddy, mentor, ...) can think of an alternative to compensate for
* the rejection comments. */
abandoned;
/* Implemented stage, the proposal is available main-stream, and should be the default way of doing. */
implemented;
/* Replaced stage, another proposal is implemented and the content of this proposal should be ignored, unless
* explicitly mentioned by an implemented proposal. */
replaced;
draft -> submitted [label="submitted by the author"];
submitted -> accepted [label="validated by comity"];
submitted -> rejected [label="rejected by comity"];
rejected -> draft;
draft -> abandoned [label="no alternative, or person to pursue"];
accepted -> implemented [label="all components merged, and the feature is usable"];
accepted -> replaced [label="better alternative found before the implementation"];
implemented -> replaced [label="better alternative found after the implementation"];
} |
||
| ### Role of the "buddy" | ||
|
|
||
| To goal for assigning a "buddy" to the RFC is multifold. The main | ||
| responsability is to make themselves available for to the author to move the RFC | ||
| along. It means keep a closer connection with them, talk and help resolve | ||
| ongoing issues and add credence to the proposal. The buddy 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. | ||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks | ||
|
|
||
| There is a danger that the additional process will hinder contribution more | ||
|
|
||
| than it would help. We should stay alert that the process is only a way to | ||
| help contribution, not an end in itself. | ||
|
|
||
| # Alternatives | ||
| [alternatives]: #alternatives | ||
|
There was a problem hiding this comment. I do not understand why If I understand correctly, when we are discussing about designs, we want explore multiple alternatives, including the first There was a problem hiding this comment. The idea is to list prior-art. This mainly shows that the author has done research. I agree that it would be nice to also have a justification of why those aren't adequate but that's not a strict requirement. Some of them might be obvious (eg: already discarded). There was a problem hiding this comment. If its for prior-art then I'm of the opinion it should be mentioned before the actual proposal, and should be discussed at that point. @nbp There was a problem hiding this comment. Submitting a RFC is already a pretty big barrier for community work, I'm a bit concerned of putting a too formal process in place. |
||
|
|
||
| Retain the current informal RFC process. The newly proposed RFC process is | ||
|
There was a problem hiding this comment. ah, so it was intended to be informal, I didn't get that :) There was a problem hiding this comment. And I aswered to all your other comments :) |
||
| designed to improve over the informal process in the following ways: | ||
|
|
||
| * Discourage unactionable or vague RFCs | ||
| * Ensure that all serious RFCs are considered equally | ||
| * Give confidence to those with a stake in the Nix ecosystem that they | ||
| understand why new features are being merged | ||
|
|
||
| As an alternative, we could adopt an even stricter RFC process than the one | ||
| proposed here. If desired, we should likely look to Python's [PEP] process for | ||
| inspiration. | ||
|
|
||
| # Unresolved questions | ||
| [unresolved]: #unresolved-questions | ||
|
|
||
| 1. Does this RFC strike a favorable balance between formality and agility? | ||
| 2. Does this RFC successfully address the aforementioned issues with the current | ||
| informal RFC process? | ||
| 3. Should we retain rejected RFCs in the archive? | ||
|
There was a problem hiding this comment. I would say "yes", they can just be marked as "rejected" like PEPs. There was a problem hiding this comment. Okay so it means adding a status metadata There was a problem hiding this comment. Another line of reasoning would be that closed PRs are still available on github and the repo only includes things we intend to implement, which are probably more relevant to users. There was a problem hiding this comment. It also means that closed PRs can get resurrected more easily in case our opinion changes over time. There was a problem hiding this comment. I think, rejected RFCs should be kept in the git history − at least the ones that raised some discussion from the community. The history of closed PRs isn't as convenient to browse as the actual git repo and is less reliable (the code of a PR can easily disappear or change if the submitter deletes or overwrites his branch iirc). There was a problem hiding this comment. If so, maybe we should make a directory for draft proposal, in which people work on, and accepting or rejecting would imply moving these files to the proper directory. -- update: replaced repository by directory There was a problem hiding this comment. The interesting bit about rejected PRs is the discussion that's happening around it, which is currently tied to github. Presuming the desire to merge is to keep the history of it, I'm not convinced that a closed PR would be much worse than a merge. It also means that it's one less thing to manage as a maintainer. There was a problem hiding this comment. When a RFC is rejected, it would be stored in the repo, and a section would be added explaining why it was rejected. In this section we could refer to discussions, but obviously those references may break. There was a problem hiding this comment. Alright, all rejected RFCs will be moved to the ./rejected folder for now 9830d2d At some point we'll be able to use the metadata to generate a website to list all the RFCs, at that point we can merge the folder back and add a "status" header. |
||
|
|
||
| [PEP]: http://legacy.python.org/dev/peps/pep-0001/ | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: capitalize Nix.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
fixed in 9322c2e