Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC to describe the RFC process #1

Merged
merged 39 commits into from Mar 18, 2017
Merged

RFC to describe the RFC process #1

merged 39 commits into from Mar 18, 2017

Conversation

zimbatm
Copy link
Member

@zimbatm zimbatm commented Feb 12, 2017

The goal is to define a process to unblock issues and PRs where there is clearly a need or good contribution but no clear outcome. The hope here is that by putting down all the context it will help the community reach a consensus. I also want to keep the process lite-weight to avoid hindering the contribution process.

The proposal is mainly lifted from the Rust community. This is mainly a starting point for the discussion, we should probably adapt the RFC process to our community.

One of the big difference with our community is that we don't have paid members that can implement the RFCs. That makes it hard to "accept" a RFC and have it implemented without having a "champion" that first agrees to be working on this. So I propose that instead we should have the RFC submitter try to gain at least traction of one other community member.

There are also some open questions regarding the feedback process. What is the acceptable response period for a feedback?

Actions after merge:

  • Add cleaned-up RFC to README.md (will be handled in Implement RFC 0001 #2)
  • Move repo to the NixOS org
  • Redirect relevant issues and PRs to this repo
  • Go through the process with another RFC to improve the process

Rendered

@zimbatm zimbatm changed the title RFC to describe the process RFC RFC to describe the RFC process Feb 12, 2017
Mainly lifted from the
[Rust community](https://github.com/rust-lang/rfcs), I hope they don't mind.
@zimbatm zimbatm mentioned this pull request Feb 12, 2017

At this point, the person submitting the RFC should find at least one "buddy"
that will help him bring the RFC to reality. The goal is to improve the
chances that the RFC is both desired and lilely to be implemented.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: lilely -> likely

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 254918a

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"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So is it OK to create a PR first, and then find a buddy (by e.g. sending an email to the list)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@zimbatm zimbatm Feb 16, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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:

  • improve changes of getting the RFC accepted.
  • Stay in contact, and query for progress?
  • Request changes and request analysis of alternatives?
  • Bring alternative to the currently proposed design?
  • Help implement the idea when the RFC is accepted?
  • Suggest implementation ideas?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@zimbatm
Copy link
Member Author

zimbatm commented Feb 13, 2017

Thanks all for your reviews. I am still looking for a "buddy" for this RFC to adhere to it's own saying, anyone interested?


- Adding, updating and removing packages in nixpkgs
- Additions only likely to be _noticed by_ other developers-of-nix,
invisible to users-of-nix.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are "users" and "developers" in this context?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was imported from the Rust RFC where developers and users are more clearly defined I think. I will remove that for now.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about having the following state machine:

new -> proposed ->  accepted -> implemented
                    |     ^
                    v     |
                    revising
       
and: new -> closed, proposed -> closed, revising -> closed, accepted -> closed
(but not implemented -> closed)

If a RFC has been accepted, but not implemented yet, we could start revising it if there are issues that need RFC level discussions.

Copy link
Member Author

@zimbatm zimbatm Feb 16, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

new -> proposed -> accepted -> implemented (draft) -> final
                       ^                |
                       |                |
                       +--  revision  --+

The draft stage should be a "handshake agreement": the user understands that the feature may change in response to data gathered from use, but the implementer understands this should only be done with adequate warning and for a really good reason. The final stage would be regarded as "set in stone": this feature will only change following a new RFC and an extended deprecation period.

Well, I wanted to give my two cents, but it looks like I dropped a buck-fifty on the table; sorry about that!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"];
}

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?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say "yes", they can just be marked as "rejected" like PEPs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay so it means adding a status metadata

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also means that closed PRs can get resurrected more easily in case our opinion changes over time.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

@nbp nbp Feb 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- Removing language features
- Big restructuring of nixpkgs
- Introduction of new interfaces or functions
- A controversial change
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, adding new package abstractions or idioms (think various auto-updaters, callPackages, composableDerivation, builderDefs, language-specific functions, ...). Deviations from the standard style make it harder for other people to understand / modify a package, so there should be a good reason for introducing them.

Of course, we should probably also better document what the standard style is :-)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added 1a37875. I'm trying to avoid over-specifying the rules. Potentially we could add a BDFL line like: if @edolstra says so :-)

@teh
Copy link

teh commented Feb 14, 2017

I think this is a good test case. Let's say I want to be your RFC-buddy, what can I do? The text says "that will help him bring the RFC to reality" - what kind of actions are expected of me?

(unrelated, maybe use the gender-neutral them, i.e. "will help them bring")

@zimbatm
Copy link
Member Author

zimbatm commented Feb 15, 2017

@teh I'm proposing 08b081a as the definition of the role, what do you think? If you still agree of being the buddy for the RFC it would make sense to catch up using a higher throughput protocol like voice, video or IRL :)

### Role of the "buddy"

To goal for assigning a "buddy" to the RFC is multifold. The main
responsability is to make himself available for to the author to move the RFC
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"make themselves" :) & "with them"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 65d32e1, keep them coming :)

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where can I find this template?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's in #2 for now. I thought it would make sense to have the implementation separate.


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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the distinction between the community and a "core team" makes sense for nix ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not. We have a "core team" but the notion is a bit fuzzy and probably changes from person to person. Removed in 48e3cef

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For nixpkgs, probably true, but for Nix the program there is certainly a core team, that consists mostly of @edolstra, with a bit of @shlevy 😄 it'd be nice to expand that group, but we might as well be explicit about it until then

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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

We don't have a definiton of who is part of the "core team"

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: This should as well include making a RFC to describe the processes by which the community interact around the projects.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing at a time :)

help contribution, not an end in itself.

# Alternatives
[alternatives]: #alternatives
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not understand why Alternatives is even a section in an RFC. What purpose does it serve?

If I understand correctly, when we are discussing about designs, we want explore multiple alternatives, including the first Design & drawbacks, and have one for each alternative. Or we should discuss the alternatives as part of the pull request for adding modifications to the RFC.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
If I would write a report where I investigate possible solutions, then I would do also as you say, have a section per alternative, and then a discussion where one (or none) is chosen. I can imagine that in a NEP (that's how we're going to call them, right? Nix Enhancement Proposal) that choice has already been made by the authors of the NEP and therefore they're only discussed briefly either before or after the actual proposal.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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:

  • improve changes of getting the RFC accepted.
  • Stay in contact, and query for progress?
  • Request changes and request analysis of alternatives?
  • Bring alternative to the currently proposed design?
  • Help implement the idea when the RFC is accepted?
  • Suggest implementation ideas?


* 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.)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. Fixed in b3db396

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"];
}

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?
Copy link
Member

@nbp nbp Feb 25, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@nbp
Copy link
Member

nbp commented Feb 26, 2017

Just a note, people seems to have started annotating their pull request / issues with the RFC tag:
https://github.com/NixOS/nixpkgs/issues?utf8=%E2%9C%93&q=RFC%20in%3Atitle

I took the current list and sorted the issues / pull requests in 3 categories: Submittable, Draft, and Rejected. I evaluated these based on my personal opinion and the following criteria:

  • the quality of the first comment. (detailed with motivation & others)
  • the impact of the changes. (number of files modified or number of person impacted is high)

Submittable as RFC:

Draft (not actionable, or not described enough) RFC:

Rejected as RFC (should be an ordinary PR):

I also added NixOS/nixpkgs#10851 (submittable) and NixOS/nixpkgs#14000 (rejected) as additional examples. I classified NixOS/nixpkgs#14000 as rejected, even if the change might have been controversial, it did not had impact out-side the limited set of developers/reviewers of this code. It would have been a good RFC, but only as part of a larger plan to introduce overlays, or to add a better cross-compilation support, but not as a single set of commits.

I think this list is a good starting point to qualify precisely what belongs as an RFC or not, and help remove these RFC tags from existing pull requests / issues.

@aneeshusa
Copy link

👍 from me for this effort! Can we please add a LICENSE (say Apache 2) up front? It's a lot harder to do down the line (see rust-lang/rfcs#1259 for example).

the Nix ecosystem. What constitutes a "substantial" change is evolving based
on community norms, but may include the following.

- Any semantic or syntactic change to the language that is not a bugfix.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style nit: remove trailing period for consistency

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks, fixed as part of 983dca3

that will help them bring the RFC to completion. The goal is to improve the
chances that the RFC is both desired and likely to be implemented.

Once the author is happy with the state of the RFC, she/he should seek for
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

she/he -> they

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the mailing-list and IRC is an acceptable way of doing that.

After a number of rounds of review the discussion should settle and a general
consensus should emerge. This bit is left intentionnaly vague and should be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

intentionally

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

* Commit everything.

If a RFC is rejected, whoever merges the RFC should do the following:
* Move the rfc to the rejected folder
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the status is rejected then what's the point of putting it in a separate folder? And how about other statuses? Will they also be put in separate folders?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What other statuses? In the beginning they're unmerged and they should get either merged (among accepted) or "merged" into the rejected folder.

Copy link
Member

@vcunat vcunat Mar 16, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From previous discussion it seemed useful that we somehow "permanently record" each rejected proposal with a summary of arguments, including why it was rejected. Keeping all the information just in PR discussion threads has some disadvantages.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to restate the goal: the goal is to keep a record of any unsuccessful PRs because on github it's possible for the submitter of the PR to remove the original code and then the context is lost.

In that regards, the rejected folder should contain any RFC that is not accepted. It would also include abandoned RFCs. If you have a better name for it I'm happy to change it.