[RFC 0093] Propose RFC Categories

0000-template.md → 0000-template-feature.md

@@ -8,51 +8,57 @@ shepherd-leader: (name to be appointed by RFC steering committee)
 related-issues: (will contain links to implementation PRs)
 ---
 
+<!--
+If you are proposing a feature to Nix, Nixpkgs, Hydra or any other
+software developped by the nix community, this is the template
+you want to use.
+-->
+
 # Summary
 [summary]: #summary
 
-One paragraph explanation of the feature.
+<!-- 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
+<!-- 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.
+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
+<!-- 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.
+instead. -->
 
 # Drawbacks
 [drawbacks]: #drawbacks
 
-Why should we *not* do this?
+<!-- Why should we *not* do this? -->
 
 # Alternatives
 [alternatives]: #alternatives
 
-What other designs have been considered? What is the impact of not doing this?
+<!-- What other designs have been considered? What is the impact of not doing this? -->
 
 # Unresolved questions
 [unresolved]: #unresolved-questions
 
-What parts of the design are still TBD or unknowns?
+<!-- 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? -->

0000-template-informational.md

@@ -0,0 +1,35 @@
+---
+information: (fill me in with a unique ident, my_new_fact)
+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)
+relates-to:
+ - [RFC 0000 my_other_information]()
+---
+
+<!--
+If you are seeking to gather consensus on a fact, or seek general acceptance about
+a new information, then use this template.
+The fact or information should be sufficiently important to require an RFC process
+Some examples are, without being an exhaustive list:
+
+- Start a talk, meetup, or social networking account that will be expected to
+  officially “represent nix”
+- Document design issues, or recording the decision to _not_ act upon something.
+- Proposing an experiment.
+- Record high-stake proof-generated insight.
+-->
+
+# Summary
+[summary]: #summary
+
+<!-- One paragraph to resume this document. -->
+
+In order to address "X", I/we propose to "Y".
+
+# My Structure
+
+<!-- This template does not have a recommended structure, please use your best
+judgment for your particular case. -->

0000-template-process.md

@@ -0,0 +1,92 @@
+---
+process: (fill me in with a unique ident, my_new_process)
+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)
+modifies:
+ - [RFC 0000 my_old_process]()
+---
+
+<!--
+If you are proposing to change a process with regard of how the nix community
+conducts, then use this template. Some examples are, without being an exhaustive list:
+
+- Change the RFC process, the organization of the issue tracker or the forum
+- Change community workflows or other comunity infrastructure
+- Amend the code of conduct and similar high level normative documents
+-->
+
+# Summary
+[summary]: #summary
+
+<!-- One paragraph to resume this document (motivation and future process). -->
+
+In order to address "X", I/we propose to "Y".
+
+# Classification
+[classification]: #classification
+
+<!-- Please check the relevant boxes (typically one) -- or add your own. -->
+
+- [ ] general habits and decision making
+- [ ] core technical protocols & processes
+- [ ] contributer efficiency support
+
+# Motivation
+[motivation]: #motivation
+
+<!-- What's wrong? Please feel encouraged to benchmark us against other
+(open source or other) ecosystems. -->
+
+# Current Process
+[as-is]: #current-process
+
+<!-- Describe the current process as it is observed out in the wild.
+If there has been a previous RFC for this process, please mention it,
+but prefer the state of the world "as-is". In a final paragraph, please
+describe its shortcomings and how they relate to the motivation.
+
+Make use of BPMN 2.0 notation, if you'd find that useful. -->
+
+# Future Process
+[to-be]: #future-process
+
+<!-- Describe the future process how you imagine it to be.
+In a final paragraph, please describe how this would satisfy the motivation.
+Please be explicit, if it only party addresses the motivation.
+
+Make use of BPMN 2.0 notation, if you'd find that useful. -->
+
+# Roles & Stakeholders
+
+<!-- Describe in abstract terms the roles involved in this process
+and how they are affected by this process change. Plotting estimated
+/ abstract time requirements of _as-is_ against _to-be_ is a plus.
+The idea is to get a better sense of the stakeholders of this process
+and their respective interestes and estimate the associated total
+costs imposed (mostly in time, can be negative) to the community.-->
+
+# Pros & Cons
+[evaluation]: #pros-and-cons
+
+<!-- Within your judgment, prefer bullet points over prose. -->
+
+## Pros
+
+
+## Cons
+
+
+# Conclusion
+[conclusion]: #conclusion
+
+<!-- In the greater scheme of things, to wat degree does your proposal
+satisfy the motivation. Is it meaningful? Is it important? Is it urgent? -->
+
+# Updates
+[updates]: #updates
+
+<!-- This space is reserved for linking or in-lining future updates to this
+process -->

README.md

@@ -1,29 +1,39 @@
 # Nix RFCs (Request For Comments)
 
-Many changes, including bug fixes and documentation improvements can be
+Many ideas, 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.
+Some ideas though are "substantial", and we ask that these be put through a
+bit of a public process and produce a consensus among the Nix community.
 
 ## When this process is followed
 
-This process is followed when one intends to make "substantial" changes to the
-Nix ecosystem. What constitutes a "substantial" change is evolving based on
+This process is followed when one intends to apply "substantial" ideas to the
+Nix ecosystem. What constitutes a "substantial" idea is evolving based on
 community norms, but may include the following.
 
 * Any semantic or syntactic change to the language that is not a bug fix
 * Removing language features
 * Big restructuring of Nixpkgs
 * Expansions to the scope of Nixpkgs (new arch, major subprojects, ...)
 * Introduction of new interfaces or functions
+* Making changes to important of formalised community processes
+* Record important proof-generated insights that affect the whole community
+* Propose an important experiment that affects the whole community
+* Document important design issues that affect the whole community
+* Start a talk/account/etc. that "officially represents the nix community"
 
 Certain changes do not require an RFC:
 
 * Adding, updating and removing packages in Nixpkgs
 * Fixing security updates and bugs that don't break interfaces
+* Starting any talk/account/etc. that does not officially represent nix
+* Making process changes to (language) sub-systems without being relevant
+  to the community as a whole
+* Conducting experiments, recording insights or documenting design issues in
+  (language) sub-systems that don't affect the community as a whole.
 
-Pull requests that contain any of the aforementioned 'substantial' changes may
+Pull requests that contain any of the aforementioned 'substantial' ideas may
 be closed if there is no RFC connected to the proposed changes.
 
 ## Terminology
@@ -73,28 +83,28 @@ the RFC has received ample discussion and enough of the tradeoffs have been
 discussed. The Shepherd Team will propose to either accept or reject the RFC
 after the FCP.
 
+##### RFC Categories
+In order to do do justice to the different aspects of documents that merit
+generation of broad community consensus via the RFC process, we cassify each
+RFC into _feature_, _process_ and _informational_ RFCs. All follow the same
+high-level process as described above, but each category requires a different
+"mode of discussion", templates, critarias and judgment that it is benefical
+to the overall RFC process to identify those categories explicitly.
+
 
 ## Process from Creation to Merge
 
-*In short, to get a major change included in Nix or Nixpkgs, one must
+*In short, to get a major change included in Nix, Nixpkgs or the Ecosystem, one must
 first get the RFC merged into the RFC repository as a markdown file under the
-`rfcs` directory. At that point the RFC is accepted and may be implemented
-with the goal of eventual inclusion into Nix or Nixpkgs.*
-
-0. Have a cool idea!
-1. Fill in the RFC. Put care into the details: RFCs that do not present
-   convincing motivation, demonstrate understanding of the impact of the design,
-   or are disingenuous about the drawbacks or alternatives tend to be
-   poorly-received. You might want to create a PR in your fork of the RFCs
-   repository to help you flesh it out with a few supporters or chat/video
-   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
-   prototype of your idea to firstly make yourself aware of potential pitfalls
-   and also help reviewers understand the RFC. Code may be able to explain some
-   issues in short.
+corresponding directory. At that point the RFC is accepted and may be implemented
+with the goal of eventual inclusion into Nix, Nixpkgs or the Ecosystem.*
+
+0. Have a cool idea r an important information!
+1. Identify its category: _feature_, _process_ or _informational_.
+2. Start with the correct template and follow the instructions and comments.
 3. Submit a pull request. As a pull request the RFC will receive design feedback
    from the larger community, and the author should be prepared to revise it in
-   response.
+   response. Leave them in draft while you're still actively working on them.
 4. For the nomination process for potential members of the RFC Shepherd Team,
    that is specific to each RFC, anyone interested can either nominate another
    person or themselves to be a potential member of the RFC Shepherd Team. This
@@ -152,28 +162,41 @@ with the goal of eventual inclusion into Nix or Nixpkgs.*
 ![RFC Process](./rfcs/0036-rfc-process.png)
 ![Review Process](./rfcs/0036-review-process.png)
 
+### Tips
+
+###### Create Prototypes
+In case your RFC is a technical proposal, you might want to prepare a
+prototype of your idea to firstly make yourself aware of potential pitfalls
+and also help reviewers understand the RFC. Code may be able to explain some
+issues in short.
+
+###### Motivation First
+In any case, it can be a good idea to elaborate the motivation first, while
+leaving the PR in draft. This helps to ensure, that when the solution is
+discussed in the future, interested participants can have a clear and refined
+picture of the problem that you try to address.
 
 ## The RFC life-cycle
 
-Once an RFC is accepted the authors may implement it and submit the feature as a
-pull request to the Nix or Nixpkgs repo. Being accepted 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. In general though this means that the
-implementation will be merged as long as there are no substantial technical
+Once an RFC is accepted the authors may implement it and for example submit the
+feature as a pull request to the Nix or Nixpkgs repo. Being accepted 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. In general though this means that
+the implementation will be merged as long as there are no substantial technical
 objections to the implementation.
 
 Furthermore, the fact that a given RFC has been accepted implies nothing about
 what priority is assigned to its implementation, nor does it imply anything
-about whether a Nix/Nixpkgs developer has been assigned the task of implementing
-the feature. While it is not necessary that the author of the RFC also write the
-implementation, it is by far the most effective way to see an RFC through to
+about whether a Nix/Nixpkgs community member has been assigned the task of
+implementing the RFC. While it is not necessary that the author of the RFC also
+does the implementation, it is by far the most effective way to see an RFC through to
 completion: authors should not expect that other project developers will take on
 responsibility for implementing their accepted feature.
 
 Minor modifications to accepted RFCs can be done in follow-up pull requests. We
-strive to write each RFC in a manner that it will reflect the final design of
-the feature; but the nature of the process means that we cannot expect every
+strive to write each RFC in a manner that it will  reflect the final state of
+the world; but the nature of the process means that we cannot expect every
 merged RFC to actually reflect what the end result will be after implementation.
 
 In general, once accepted, RFCs should not be substantially changed. Only very