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 <title>Reviewing contributions</title>
7 <warning>
8 <para>
9 The following section is a draft, and the policy for reviewing is still
10 being discussed in issues such as
11 <link
12 xlink:href="https://github.com/NixOS/nixpkgs/issues/11166">#11166
13 </link> and
14 <link
15 xlink:href="https://github.com/NixOS/nixpkgs/issues/20836">#20836
16 </link>.
17 </para>
18 </warning>
19 <para>
20 The nixpkgs project receives a fairly high number of contributions via GitHub
21 pull-requests. Reviewing and approving these is an important task and a way
22 to contribute to the project.
23 </para>
24 <para>
25 The high change rate of nixpkgs makes any pull request that remains open for
26 too long subject to conflicts that will require extra work from the submitter
27 or the merger. Reviewing pull requests in a timely manner and being
28 responsive to the comments is the key to avoid these. GitHub provides sort
29 filters that can be used to see the
30 <link
31 xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc">most
32 recently</link> and the
33 <link
34 xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc">least
35 recently</link> updated pull-requests. We highly encourage looking at
36 <link xlink:href="https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone">
37 this list of ready to merge, unreviewed pull requests</link>.
38 </para>
39 <para>
40 When reviewing a pull request, please always be nice and polite.
41 Controversial changes can lead to controversial opinions, but it is important
42 to respect every community member and their work.
43 </para>
44 <para>
45 GitHub provides reactions as a simple and quick way to provide feedback to
46 pull-requests or any comments. The thumb-down reaction should be used with
47 care and if possible accompanied with some explanation so the submitter has
48 directions to improve their contribution.
49 </para>
50 <para>
51 Pull-request reviews should include a list of what has been reviewed in a
52 comment, so other reviewers and mergers can know the state of the review.
53 </para>
54 <para>
55 All the review template samples provided in this section are generic and
56 meant as examples. Their usage is optional and the reviewer is free to adapt
57 them to their liking.
58 </para>
59 <section xml:id="reviewing-contributions-package-updates">
60 <title>Package updates</title>
61
62 <para>
63 A package update is the most trivial and common type of pull-request. These
64 pull-requests mainly consist of updating the version part of the package
65 name and the source hash.
66 </para>
67
68 <para>
69 It can happen that non-trivial updates include patches or more complex
70 changes.
71 </para>
72
73 <para>
74 Reviewing process:
75 </para>
76
77 <itemizedlist>
78 <listitem>
79 <para>
80 Add labels to the pull-request. (Requires commit rights)
81 </para>
82 <itemizedlist>
83 <listitem>
84 <para>
85 <literal>8.has: package (update)</literal> and any topic label that fit
86 the updated package.
87 </para>
88 </listitem>
89 </itemizedlist>
90 </listitem>
91 <listitem>
92 <para>
93 Ensure that the package versioning fits the guidelines.
94 </para>
95 </listitem>
96 <listitem>
97 <para>
98 Ensure that the commit text fits the guidelines.
99 </para>
100 </listitem>
101 <listitem>
102 <para>
103 Ensure that the package maintainers are notified.
104 </para>
105 <itemizedlist>
106 <listitem>
107 <para>
108 <link xlink:href="https://help.github.com/articles/about-codeowners/">CODEOWNERS</link>
109 will make GitHub notify users based on the submitted changes, but it can
110 happen that it misses some of the package maintainers.
111 </para>
112 </listitem>
113 </itemizedlist>
114 </listitem>
115 <listitem>
116 <para>
117 Ensure that the meta field information is correct.
118 </para>
119 <itemizedlist>
120 <listitem>
121 <para>
122 License can change with version updates, so it should be checked to
123 match the upstream license.
124 </para>
125 </listitem>
126 <listitem>
127 <para>
128 If the package has no maintainer, a maintainer must be set. This can be
129 the update submitter or a community member that accepts to take
130 maintainership of the package.
131 </para>
132 </listitem>
133 </itemizedlist>
134 </listitem>
135 <listitem>
136 <para>
137 Ensure that the code contains no typos.
138 </para>
139 </listitem>
140 <listitem>
141 <para>
142 Building the package locally.
143 </para>
144 <itemizedlist>
145 <listitem>
146 <para>
147 Pull-requests are often targeted to the master or staging branch, and
148 building the pull-request locally when it is submitted can trigger many
149 source builds.
150 </para>
151 <para>
152 It is possible to rebase the changes on nixos-unstable or
153 nixpkgs-unstable for easier review by running the following commands
154 from a nixpkgs clone.
155<screen>
156$ git remote add channels https://github.com/NixOS/nixpkgs-channels.git <co
157 xml:id='reviewing-rebase-1' />
158$ git fetch channels nixos-unstable <co xml:id='reviewing-rebase-2' />
159$ git fetch origin pull/PRNUMBER/head <co xml:id='reviewing-rebase-3' />
160$ git rebase --onto nixos-unstable BASEBRANCH FETCH_HEAD <co
161 xml:id='reviewing-rebase-4' />
162</screen>
163 <calloutlist>
164 <callout arearefs='reviewing-rebase-1'>
165 <para>
166 This should be done only once to be able to fetch channel branches
167 from the nixpkgs-channels repository.
168 </para>
169 </callout>
170 <callout arearefs='reviewing-rebase-2'>
171 <para>
172 Fetching the nixos-unstable branch.
173 </para>
174 </callout>
175 <callout arearefs='reviewing-rebase-3'>
176 <para>
177 Fetching the pull-request changes, <varname>PRNUMBER</varname> is the
178 number at the end of the pull-request title and
179 <varname>BASEBRANCH</varname> the base branch of the pull-request.
180 </para>
181 </callout>
182 <callout arearefs='reviewing-rebase-4'>
183 <para>
184 Rebasing the pull-request changes to the nixos-unstable branch.
185 </para>
186 </callout>
187 </calloutlist>
188 </para>
189 </listitem>
190 <listitem>
191 <para>
192 The <link xlink:href="https://github.com/madjar/nox">nox</link> tool can
193 be used to review a pull-request content in a single command. It doesn't
194 rebase on a channel branch so it might trigger multiple source builds.
195 <varname>PRNUMBER</varname> should be replaced by the number at the end
196 of the pull-request title.
197 </para>
198<screen>
199$ nix-shell -p nox --run "nox-review -k pr PRNUMBER"
200</screen>
201 </listitem>
202 </itemizedlist>
203 </listitem>
204 <listitem>
205 <para>
206 Running every binary.
207 </para>
208 </listitem>
209 </itemizedlist>
210
211 <example xml:id="reviewing-contributions-sample-package-update">
212 <title>Sample template for a package update review</title>
213<screen>
214##### Reviewed points
215
216- [ ] package name fits guidelines
217- [ ] package version fits guidelines
218- [ ] package build on ARCHITECTURE
219- [ ] executables tested on ARCHITECTURE
220- [ ] all depending packages build
221
222##### Possible improvements
223
224##### Comments
225
226</screen>
227 </example>
228 </section>
229 <section xml:id="reviewing-contributions-new-packages">
230 <title>New packages</title>
231
232 <para>
233 New packages are a common type of pull-requests. These pull requests
234 consists in adding a new nix-expression for a package.
235 </para>
236
237 <para>
238 Reviewing process:
239 </para>
240
241 <itemizedlist>
242 <listitem>
243 <para>
244 Add labels to the pull-request. (Requires commit rights)
245 </para>
246 <itemizedlist>
247 <listitem>
248 <para>
249 <literal>8.has: package (new)</literal> and any topic label that fit the
250 new package.
251 </para>
252 </listitem>
253 </itemizedlist>
254 </listitem>
255 <listitem>
256 <para>
257 Ensure that the package versioning is fitting the guidelines.
258 </para>
259 </listitem>
260 <listitem>
261 <para>
262 Ensure that the commit name is fitting the guidelines.
263 </para>
264 </listitem>
265 <listitem>
266 <para>
267 Ensure that the meta field contains correct information.
268 </para>
269 <itemizedlist>
270 <listitem>
271 <para>
272 License must be checked to be fitting upstream license.
273 </para>
274 </listitem>
275 <listitem>
276 <para>
277 Platforms should be set or the package will not get binary substitutes.
278 </para>
279 </listitem>
280 <listitem>
281 <para>
282 A maintainer must be set, this can be the package submitter or a
283 community member that accepts to take maintainership of the package.
284 </para>
285 </listitem>
286 </itemizedlist>
287 </listitem>
288 <listitem>
289 <para>
290 Ensure that the code contains no typos.
291 </para>
292 </listitem>
293 <listitem>
294 <para>
295 Ensure the package source.
296 </para>
297 <itemizedlist>
298 <listitem>
299 <para>
300 Mirrors urls should be used when available.
301 </para>
302 </listitem>
303 <listitem>
304 <para>
305 The most appropriate function should be used (e.g. packages from GitHub
306 should use <literal>fetchFromGitHub</literal>).
307 </para>
308 </listitem>
309 </itemizedlist>
310 </listitem>
311 <listitem>
312 <para>
313 Building the package locally.
314 </para>
315 </listitem>
316 <listitem>
317 <para>
318 Running every binary.
319 </para>
320 </listitem>
321 </itemizedlist>
322
323 <example xml:id="reviewing-contributions-sample-new-package">
324 <title>Sample template for a new package review</title>
325<screen>
326##### Reviewed points
327
328- [ ] package path fits guidelines
329- [ ] package name fits guidelines
330- [ ] package version fits guidelines
331- [ ] package build on ARCHITECTURE
332- [ ] executables tested on ARCHITECTURE
333- [ ] `meta.description` is set and fits guidelines
334- [ ] `meta.license` fits upstream license
335- [ ] `meta.platforms` is set
336- [ ] `meta.maintainers` is set
337- [ ] build time only dependencies are declared in `nativeBuildInputs`
338- [ ] source is fetched using the appropriate function
339- [ ] phases are respected
340- [ ] patches that are remotely available are fetched with `fetchpatch`
341
342##### Possible improvements
343
344##### Comments
345
346</screen>
347 </example>
348 </section>
349 <section xml:id="reviewing-contributions-module-updates">
350 <title>Module updates</title>
351
352 <para>
353 Module updates are submissions changing modules in some ways. These often
354 contains changes to the options or introduce new options.
355 </para>
356
357 <para>
358 Reviewing process
359 </para>
360
361 <itemizedlist>
362 <listitem>
363 <para>
364 Add labels to the pull-request. (Requires commit rights)
365 </para>
366 <itemizedlist>
367 <listitem>
368 <para>
369 <literal>8.has: module (update)</literal> and any topic label that fit
370 the module.
371 </para>
372 </listitem>
373 </itemizedlist>
374 </listitem>
375 <listitem>
376 <para>
377 Ensure that the module maintainers are notified.
378 </para>
379 <itemizedlist>
380 <listitem>
381 <para>
382 <link xlink:href="https://help.github.com/articles/about-codeowners/">CODEOWNERS</link>
383 will make GitHub notify users based on the submitted changes, but it can
384 happen that it misses some of the package maintainers.
385 </para>
386 </listitem>
387 </itemizedlist>
388 </listitem>
389 <listitem>
390 <para>
391 Ensure that the module tests, if any, are succeeding.
392 </para>
393 </listitem>
394 <listitem>
395 <para>
396 Ensure that the introduced options are correct.
397 </para>
398 <itemizedlist>
399 <listitem>
400 <para>
401 Type should be appropriate (string related types differs in their
402 merging capabilities, <literal>optionSet</literal> and
403 <literal>string</literal> types are deprecated).
404 </para>
405 </listitem>
406 <listitem>
407 <para>
408 Description, default and example should be provided.
409 </para>
410 </listitem>
411 </itemizedlist>
412 </listitem>
413 <listitem>
414 <para>
415 Ensure that option changes are backward compatible.
416 </para>
417 <itemizedlist>
418 <listitem>
419 <para>
420 <literal>mkRenamedOptionModule</literal> and
421 <literal>mkAliasOptionModule</literal> functions provide way to make
422 option changes backward compatible.
423 </para>
424 </listitem>
425 </itemizedlist>
426 </listitem>
427 <listitem>
428 <para>
429 Ensure that removed options are declared with
430 <literal>mkRemovedOptionModule</literal>
431 </para>
432 </listitem>
433 <listitem>
434 <para>
435 Ensure that changes that are not backward compatible are mentioned in
436 release notes.
437 </para>
438 </listitem>
439 <listitem>
440 <para>
441 Ensure that documentations affected by the change is updated.
442 </para>
443 </listitem>
444 </itemizedlist>
445
446 <example xml:id="reviewing-contributions-sample-module-update">
447 <title>Sample template for a module update review</title>
448<screen>
449##### Reviewed points
450
451- [ ] changes are backward compatible
452- [ ] removed options are declared with `mkRemovedOptionModule`
453- [ ] changes that are not backward compatible are documented in release notes
454- [ ] module tests succeed on ARCHITECTURE
455- [ ] options types are appropriate
456- [ ] options description is set
457- [ ] options example is provided
458- [ ] documentation affected by the changes is updated
459
460##### Possible improvements
461
462##### Comments
463
464</screen>
465 </example>
466 </section>
467 <section xml:id="reviewing-contributions-new-modules">
468 <title>New modules</title>
469
470 <para>
471 New modules submissions introduce a new module to NixOS.
472 </para>
473
474 <itemizedlist>
475 <listitem>
476 <para>
477 Add labels to the pull-request. (Requires commit rights)
478 </para>
479 <itemizedlist>
480 <listitem>
481 <para>
482 <literal>8.has: module (new)</literal> and any topic label that fit the
483 module.
484 </para>
485 </listitem>
486 </itemizedlist>
487 </listitem>
488 <listitem>
489 <para>
490 Ensure that the module tests, if any, are succeeding.
491 </para>
492 </listitem>
493 <listitem>
494 <para>
495 Ensure that the introduced options are correct.
496 </para>
497 <itemizedlist>
498 <listitem>
499 <para>
500 Type should be appropriate (string related types differs in their
501 merging capabilities, <literal>optionSet</literal> and
502 <literal>string</literal> types are deprecated).
503 </para>
504 </listitem>
505 <listitem>
506 <para>
507 Description, default and example should be provided.
508 </para>
509 </listitem>
510 </itemizedlist>
511 </listitem>
512 <listitem>
513 <para>
514 Ensure that module <literal>meta</literal> field is present
515 </para>
516 <itemizedlist>
517 <listitem>
518 <para>
519 Maintainers should be declared in <literal>meta.maintainers</literal>.
520 </para>
521 </listitem>
522 <listitem>
523 <para>
524 Module documentation should be declared with
525 <literal>meta.doc</literal>.
526 </para>
527 </listitem>
528 </itemizedlist>
529 </listitem>
530 <listitem>
531 <para>
532 Ensure that the module respect other modules functionality.
533 </para>
534 <itemizedlist>
535 <listitem>
536 <para>
537 For example, enabling a module should not open firewall ports by
538 default.
539 </para>
540 </listitem>
541 </itemizedlist>
542 </listitem>
543 </itemizedlist>
544
545 <example xml:id="reviewing-contributions-sample-new-module">
546 <title>Sample template for a new module review</title>
547<screen>
548##### Reviewed points
549
550- [ ] module path fits the guidelines
551- [ ] module tests succeed on ARCHITECTURE
552- [ ] options have appropriate types
553- [ ] options have default
554- [ ] options have example
555- [ ] options have descriptions
556- [ ] No unneeded package is added to environment.systemPackages
557- [ ] meta.maintainers is set
558- [ ] module documentation is declared in meta.doc
559
560##### Possible improvements
561
562##### Comments
563
564</screen>
565 </example>
566 </section>
567 <section xml:id="reviewing-contributions-other-submissions">
568 <title>Other submissions</title>
569
570 <para>
571 Other type of submissions requires different reviewing steps.
572 </para>
573
574 <para>
575 If you consider having enough knowledge and experience in a topic and would
576 like to be a long-term reviewer for related submissions, please contact the
577 current reviewers for that topic. They will give you information about the
578 reviewing process. The main reviewers for a topic can be hard to find as
579 there is no list, but checking past pull-requests to see who reviewed or
580 git-blaming the code to see who committed to that topic can give some hints.
581 </para>
582
583 <para>
584 Container system, boot system and library changes are some examples of the
585 pull requests fitting this category.
586 </para>
587 </section>
588 <section xml:id="reviewing-contributions--merging-pull-requests">
589 <title>Merging pull-requests</title>
590
591 <para>
592 It is possible for community members that have enough knowledge and
593 experience on a special topic to contribute by merging pull requests.
594 </para>
595
596 <para>
597 TODO: add the procedure to request merging rights.
598 </para>
599
600<!--
601The following paragraph about how to deal with unactive contributors is just a
602proposition and should be modified to what the community agrees to be the right
603policy.
604
605<para>Please note that contributors with commit rights unactive for more than
606 three months will have their commit rights revoked.</para>
607-->
608
609 <para>
610 In a case a contributor leaves definitively the Nix community, he should
611 create an issue or post on
612 <link
613 xlink:href="https://discourse.nixos.org">Discourse</link> with
614 references of packages and modules he maintains so the maintainership can be
615 taken over by other contributors.
616 </para>
617 </section>
618</chapter>