mirror of
https://github.com/NixOS/rfcs.git
synced 2025-12-16 14:01:15 +01:00
RFC to describe the RFC process
Mainly lifted from the [Rust community](https://github.com/rust-lang/rfcs), I hope they don't mind.
This commit is contained in:
parent
21fd6a714d
commit
81cca13346
1 changed files with 132 additions and 0 deletions
132
rfcs/0000-rfc-process.md
Normal file
132
rfcs/0000-rfc-process.md
Normal file
|
|
@ -0,0 +1,132 @@
|
|||
- Feature Name: rfc-process
|
||||
- Start Date: 2017-02-12
|
||||
- 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 GitHub issues, PRs and mailing-list discussions where
|
||||
significant contribution was put in but then grind to a halt. Usually because
|
||||
there is either not a clear desirable outcome, the direction taken is not
|
||||
desired (PR) or the stakeholder doesn't have enough brain space available to
|
||||
think about the issue.
|
||||
|
||||
The motiviation for introducing this process is to avoid losing all that work.
|
||||
By putting contributors through the RFC process for significant changes, it
|
||||
should help clarify the path for contribution when the other routes aren't
|
||||
suitable.
|
||||
|
||||
# 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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
- Any semantic or syntactic change to the language that is not a bugfix.
|
||||
- Removing language features
|
||||
- Big restructuring of nixpkgs
|
||||
- Introduction of new interfaces or functions
|
||||
|
||||
Some changes do not require an RFC:
|
||||
|
||||
- Adding, updating and removing packages in nixpkgs
|
||||
- Additions only likely to be _noticed by_ other developers-of-nix,
|
||||
invisible to users-of-nix.
|
||||
|
||||
If you submit a pull request to implement a new feature without going
|
||||
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 must first
|
||||
get the RFC merged into the RFC repo as a markdown file. At that point the RFC
|
||||
is 'active' and may be implemented with the goal of eventual inclusion into
|
||||
the Nix ecosystem.
|
||||
|
||||
* Fork the RFC repo https://github.com/NixOS/rfcs
|
||||
* Copy `0000-template.md` to `rfcs/0000-my-feature.md` (where
|
||||
'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.
|
||||
|
||||
Eventually, somebody on the [core team] will either accept the RFC by
|
||||
merging the pull request, at which point the RFC is 'active', or
|
||||
reject it by closing the pull request.
|
||||
|
||||
Whomever merges the RFC should do the following:
|
||||
|
||||
* 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.)
|
||||
* 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
|
||||
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.
|
||||
|
||||
# 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
|
||||
|
||||
Retain the current informal RFC process. The newly proposed RFC process is
|
||||
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?
|
||||
|
||||
[PEP]: http://legacy.python.org/dev/peps/pep-0001/
|
||||
Loading…
Add table
Add a link
Reference in a new issue