-
-
Notifications
You must be signed in to change notification settings - Fork 162
/
Copy path0001-rfc-process.md
154 lines (115 loc) · 6.04 KB
/
0001-rfc-process.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
---
feature: rfc-process
start-date: 2017-02-12
author: zimbatm
co-authors: teh, MoreTea
related-issues: https://github.com/zimbatm/rfcs/pull/2
---
# 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.
Therefore, the purpose of this RFC is to introduce a process that allows to
bring the discussion upfront and avoid unnecesary implementations. It forces
developers to formulate their ideas without getting bogged down into
implementation details. This RFC is used to bootstrap the process and further
RFCs can be used to refine the process.
# 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.
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 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
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
* Expansions to the scope of nixpkgs (new arch, major subprojects, ...)
* Introduction of new interfaces or functions
Certain changes do not require an RFC:
* Adding, updating and removing packages in nixpkgs
* Fixing security updates and bugs that don't break interfaces
Pull requests that contain any of the afore mentioned 'substantial' changes may be closed if there is no RFC connected to the proposed changes.
## Description of the process
In short, to get a major feature added to the Nix ecosystem, one should first
go through the RFC process in order to improve the likelyhood of inclusion.
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 'my-feature' is
descriptive. don't assign an RFC number yet).
* Fill in the RFC
* Submit a pull request. Rename the rfcs with the PR number. (eg: PR #123 would
be `rfcs/0123-my-feature.md`)
At this point, the person submitting the RFC should find at least one "co-author"
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, they should seek for
wider community review by stating the readyness of the work. Advertisement on
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 intentionally vague and should be
refined in the future. We don't have a technical commitee so controversial
changes will be rejected by default.
If a RFC is accepted then authors may implement it and submit the feature as a
pull request to the Nix or nixpkgs repo. An 'accepted' RFC 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.
Whoever merges the RFC should do the following:
* Fill in the remaining metadata in the RFC header, including links for the
original pull request(s) and the newly created issue.
* Commit everything.
If a RFC is rejected, whoever merges the RFC should do the following:
* Move the rfc to the rejected folder
* Fill in the remaining metadata in the RFC header, including links for the
original pull request(s) and the newly created issue.
* Include a summary reason for the rejection
* Commit everything
## Role of the "co-author"
The goal for assigning a "co-author" is to help move the RFC along.
The co-author should:
* be available for discussion with the main author
* respond to inquiries in a timely manner
* help with fixing minor issues like typos so community discussion can stay
on design issues
The co-author 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 risk 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
To be solved in the future:
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?
[PEP]: http://legacy.python.org/dev/peps/pep-0001/