pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-reviewing-contributions">
6
7<title>Reviewing contributions</title>
8
9<warning>
10 <para>The following section is a draft and reviewing policy is still being
11 discussed.</para>
12</warning>
13
14<para>The nixpkgs projects receives a fairly high number of contributions via
15 GitHub pull-requests. Reviewing and approving these is an important task and a
16 way to contribute to the project.</para>
17
18<para>The high change rate of nixpkgs make any pull request that is open for
19 long enough subject to conflicts that will require extra work from the
20 submitter or the merger. Reviewing pull requests in a timely manner and being
21 responsive to the comments is the key to avoid these. GitHub provides sort
22 filters that can be used to see the <link
23 xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most
24 recently</link> and the <link
25 xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least
26 recently</link> updated pull-requests.</para>
27
28<para>When reviewing a pull request, please always be nice and polite.
29 Controversial changes can lead to controversial opinions, but it is important
30 to respect every community members and their work.</para>
31
32<para>GitHub provides reactions, they are a simple and quick way to provide
33 feedback to pull-requests or any comments. The thumb-down reaction should be
34 used with care and if possible accompanied with some explanations so the
35 submitter has directions to improve his contribution.</para>
36
37<para>Pull-requests reviews should include a list of what has been reviewed in a
38 comment, so other reviewers and mergers can know the state of the
39 review.</para>
40
41<para>All the review template samples provided in this section are generic and
42 meant as examples. Their usage is optional and the reviewer is free to adapt
43 them to his liking.</para>
44
45<section><title>Package updates</title>
46
47<para>A package update is the most trivial and common type of pull-request.
48 These pull-requests mainly consist in updating the version part of the package
49 name and the source hash.</para>
50<para>It can happen that non trivial updates include patches or more complex
51 changes.</para>
52
53<para>Reviewing process:</para>
54
55<itemizedlist>
56 <listitem><para>Add labels to the pull-request. (Requires commit
57 rights)</para>
58 <itemizedlist>
59 <listitem><para><literal>8.has: package (update)</literal> and any topic
60 label that fit the updated package.</para></listitem>
61 </itemizedlist>
62 </listitem>
63 <listitem><para>Ensure that the package versioning is fitting the
64 guidelines.</para></listitem>
65 <listitem><para>Ensure that the commit text is fitting the
66 guidelines.</para></listitem>
67 <listitem><para>Ensure that the package maintainers are notified.</para>
68 <itemizedlist>
69 <listitem><para>mention-bot usually notify GitHub users based on the
70 submitted changes, but it can happen that it misses some of the
71 package maintainers.</para></listitem>
72 </itemizedlist>
73 </listitem>
74 <listitem><para>Ensure that the meta field contains correct
75 information.</para>
76 <itemizedlist>
77 <listitem><para>License can change with version updates, so it should be
78 checked to be fitting upstream license.</para></listitem>
79 <listitem><para>If the package has no maintainer, a maintainer must be
80 set. This can be the update submitter or a community member that
81 accepts to take maintainership of the package.</para></listitem>
82 </itemizedlist>
83 </listitem>
84 <listitem><para>Ensure that the code contains no typos.</para></listitem>
85 <listitem><para>Building the package locally.</para>
86 <itemizedlist>
87 <listitem><para>Pull-requests are often targeted to the master or staging
88 branch so building the pull-request locally as it is submitted can
89 trigger a large amount of source builds.</para>
90 <para>It is possible to rebase the changes on nixos-unstable or
91 nixpkgs-unstable for easier review by running the following commands
92 from a nixpkgs clone.
93<screen>
94$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git <co
95 xml:id='reviewing-rebase-1' />
96$ git fetch channels nixos-unstable <co xml:id='reviewing-rebase-2' />
97$ git fetch origin pull/PRNUMBER/head <co xml:id='reviewing-rebase-3' />
98$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
99 xml:id='reviewing-rebase-4' />
100</screen>
101 <calloutlist>
102 <callout arearefs='reviewing-rebase-1'>
103 <para>This should be done only once to be able to fetch channel
104 branches from the nixpkgs-channels repository.</para>
105 </callout>
106 <callout arearefs='reviewing-rebase-2'>
107 <para>Fetching the nixos-unstable branch.</para>
108 </callout>
109 <callout arearefs='reviewing-rebase-3'>
110 <para>Fetching the pull-request changes, <varname>PRNUMBER</varname>
111 is the number at the end of the pull-request title and
112 <varname>BASEBRANCH</varname> the base branch of the
113 pull-request.</para>
114 </callout>
115 <callout arearefs='reviewing-rebase-3'>
116 <para>Rebasing the pull-request changes to the nixos-unstable
117 branch.</para>
118 </callout>
119 </calloutlist>
120 </para>
121 </listitem>
122 <listitem>
123 <para>The <link xlink:href="https://github.com/madjar/nox">nox</link>
124 tool can be used to review a pull-request content in a single command.
125 It doesn't rebase on a channel branch so it might trigger multiple
126 source builds. <varname>PRNUMBER</varname> should be replaced by the
127 number at the end of the pull-request title.</para>
128<screen>
129$ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
130</screen>
131 </listitem>
132 </itemizedlist>
133 </listitem>
134 <listitem><para>Running every binary.</para></listitem>
135</itemizedlist>
136
137<example><title>Sample template for a package update review</title>
138<screen>
139##### Reviewed points
140
141- [ ] package name fits guidelines
142- [ ] package version fits guidelines
143- [ ] package build on ARCHITECTURE
144- [ ] executables tested on ARCHITECTURE
145- [ ] all depending packages build
146
147##### Possible improvements
148
149##### Comments
150
151</screen></example>
152</section>
153
154<section><title>New packages</title>
155
156<para>New packages are a common type of pull-requests. These pull requests
157 consists in adding a new nix-expression for a package.</para>
158
159<para>Reviewing process:</para>
160
161<itemizedlist>
162 <listitem><para>Add labels to the pull-request. (Requires commit
163 rights)</para>
164 <itemizedlist>
165 <listitem><para><literal>8.has: package (new)</literal> and any topic
166 label that fit the new package.</para></listitem>
167 </itemizedlist>
168 </listitem>
169 <listitem><para>Ensure that the package versioning is fitting the
170 guidelines.</para></listitem>
171 <listitem><para>Ensure that the commit name is fitting the
172 guidelines.</para></listitem>
173 <listitem><para>Ensure that the meta field contains correct
174 information.</para>
175 <itemizedlist>
176 <listitem><para>License must be checked to be fitting upstream
177 license.</para></listitem>
178 <listitem><para>Platforms should be set or the package will not get binary
179 substitutes.</para></listitem>
180 <listitem><para>A maintainer must be set, this can be the package
181 submitter or a community member that accepts to take maintainership of
182 the package.</para></listitem>
183 </itemizedlist>
184 </listitem>
185 <listitem><para>Ensure that the code contains no typos.</para></listitem>
186 <listitem><para>Ensure the package source.</para>
187 <itemizedlist>
188 <listitem><para>Mirrors urls should be used when
189 available.</para></listitem>
190 <listitem><para>The most appropriate function should be used (e.g.
191 packages from GitHub should use
192 <literal>fetchFromGitHub</literal>).</para></listitem>
193 </itemizedlist>
194 </listitem>
195 <listitem><para>Building the package locally.</para></listitem>
196 <listitem><para>Running every binary.</para></listitem>
197</itemizedlist>
198
199<example><title>Sample template for a new package review</title>
200<screen>
201##### Reviewed points
202
203- [ ] package path fits guidelines
204- [ ] package name fits guidelines
205- [ ] package version fits guidelines
206- [ ] package build on ARCHITECTURE
207- [ ] executables tested on ARCHITECTURE
208- [ ] `meta.description` is set and fits guidelines
209- [ ] `meta.license` fits upstream license
210- [ ] `meta.platforms` is set
211- [ ] `meta.maintainers` is set
212- [ ] build time only dependencies are declared in `nativeBuildInputs`
213- [ ] source is fetched using the appropriate function
214- [ ] phases are respected
215- [ ] patches that are remotely available are fetched with `fetchpatch`
216
217##### Possible improvements
218
219##### Comments
220
221</screen></example>
222</section>
223
224<section><title>Module updates</title>
225
226<para>Module updates are submissions changing modules in some ways. These often
227 contains changes to the options or introduce new options.</para>
228
229<para>Reviewing process</para>
230
231<itemizedlist>
232 <listitem><para>Add labels to the pull-request. (Requires commit
233 rights)</para>
234 <itemizedlist>
235 <listitem><para><literal>8.has: module (update)</literal> and any topic
236 label that fit the module.</para></listitem>
237 </itemizedlist>
238 </listitem>
239 <listitem><para>Ensure that the module maintainers are notified.</para>
240 <itemizedlist>
241 <listitem><para>Mention-bot notify GitHub users based on the submitted
242 changes, but it can happen that it miss some of the package
243 maintainers.</para></listitem>
244 </itemizedlist>
245 </listitem>
246 <listitem><para>Ensure that the module tests, if any, are
247 succeeding.</para></listitem>
248 <listitem><para>Ensure that the introduced options are correct.</para>
249 <itemizedlist>
250 <listitem><para>Type should be appropriate (string related types differs
251 in their merging capabilities, <literal>optionSet</literal> and
252 <literal>string</literal> types are deprecated).</para></listitem>
253 <listitem><para>Description, default and example should be
254 provided.</para></listitem>
255 </itemizedlist>
256 </listitem>
257 <listitem><para>Ensure that option changes are backward compatible.</para>
258 <itemizedlist>
259 <listitem><para><literal>mkRenamedOptionModule</literal> and
260 <literal>mkAliasOptionModule</literal> functions provide way to make
261 option changes backward compatible.</para></listitem>
262 </itemizedlist>
263 </listitem>
264 <listitem><para>Ensure that removed options are declared with
265 <literal>mkRemovedOptionModule</literal></para></listitem>
266 <listitem><para>Ensure that changes that are not backward compatible are
267 mentioned in release notes.</para></listitem>
268 <listitem><para>Ensure that documentations affected by the change is
269 updated.</para></listitem>
270</itemizedlist>
271
272<example><title>Sample template for a module update review</title>
273<screen>
274##### Reviewed points
275
276- [ ] changes are backward compatible
277- [ ] removed options are declared with `mkRemovedOptionModule`
278- [ ] changes that are not backward compatible are documented in release notes
279- [ ] module tests succeed on ARCHITECTURE
280- [ ] options types are appropriate
281- [ ] options description is set
282- [ ] options example is provided
283- [ ] documentation affected by the changes is updated
284
285##### Possible improvements
286
287##### Comments
288
289</screen></example>
290</section>
291
292<section><title>New modules</title>
293
294<para>New modules submissions introduce a new module to NixOS.</para>
295
296<itemizedlist>
297 <listitem><para>Add labels to the pull-request. (Requires commit
298 rights)</para>
299 <itemizedlist>
300 <listitem><para><literal>8.has: module (new)</literal> and any topic label
301 that fit the module.</para></listitem>
302 </itemizedlist>
303 </listitem>
304 <listitem><para>Ensure that the module tests, if any, are
305 succeeding.</para></listitem>
306 <listitem><para>Ensure that the introduced options are correct.</para>
307 <itemizedlist>
308 <listitem><para>Type should be appropriate (string related types differs
309 in their merging capabilities, <literal>optionSet</literal> and
310 <literal>string</literal> types are deprecated).</para></listitem>
311 <listitem><para>Description, default and example should be
312 provided.</para></listitem>
313 </itemizedlist>
314 </listitem>
315 <listitem><para>Ensure that module <literal>meta</literal> field is
316 present</para>
317 <itemizedlist>
318 <listitem><para>Maintainers should be declared in
319 <literal>meta.maintainers</literal>.</para></listitem>
320 <listitem><para>Module documentation should be declared with
321 <literal>meta.doc</literal>.</para></listitem>
322 </itemizedlist>
323 </listitem>
324 <listitem><para>Ensure that the module respect other modules
325 functionality.</para>
326 <itemizedlist>
327 <listitem><para>For example, enabling a module should not open firewall
328 ports by default.</para></listitem>
329 </itemizedlist>
330 </listitem>
331</itemizedlist>
332
333<example><title>Sample template for a new module review</title>
334<screen>
335##### Reviewed points
336
337- [ ] module path fits the guidelines
338- [ ] module tests succeed on ARCHITECTURE
339- [ ] options have appropriate types
340- [ ] options have default
341- [ ] options have example
342- [ ] options have descriptions
343- [ ] No unneeded package is added to system.environmentPackages
344- [ ] meta.maintainers is set
345- [ ] module documentation is declared in meta.doc
346
347##### Possible improvements
348
349##### Comments
350
351</screen></example>
352</section>
353
354<section><title>Other submissions</title>
355
356<para>Other type of submissions requires different reviewing steps.</para>
357
358<para>If you consider having enough knowledge and experience in a topic and
359 would like to be a long-term reviewer for related submissions, please contact
360 the current reviewers for that topic. They will give you information about the
361 reviewing process.
362The main reviewers for a topic can be hard to find as there is no list, but
363checking past pull-requests to see who reviewed or git-blaming the code to see
364who committed to that topic can give some hints.</para>
365
366<para>Container system, boot system and library changes are some examples of the
367 pull requests fitting this category.</para>
368
369</section>
370
371<section><title>Merging pull-requests</title>
372
373<para>It is possible for community members that have enough knowledge and
374 experience on a special topic to contribute by merging pull requests.</para>
375
376<para>TODO: add the procedure to request merging rights.</para>
377
378<!--
379The following paragraph about how to deal with unactive contributors is just a
380proposition and should be modified to what the community agrees to be the right
381policy.
382
383<para>Please note that contributors with commit rights unactive for more than
384 three months will have their commit rights revoked.</para>
385-->
386
387<para>In a case a contributor leaves definitively the Nix community, he should
388 create an issue or notify the mailing list with references of packages and
389 modules he maintains so the maintainership can be taken over by other
390 contributors.</para>
391
392</section>
393</chapter>