pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-submitting-changes">
4
5<title>Submitting changes</title>
6
7<section>
8<title>Making patches</title>
9
10<itemizedlist>
11<listitem>
12<para>Read <link xlink:href="https://nixos.org/nixpkgs/manual/">Manual (How to write packages for Nix)</link>.</para>
13</listitem>
14
15<listitem>
16<para>Fork the repository on GitHub.</para>
17</listitem>
18
19<listitem>
20<para>Create a branch for your future fix.
21
22<itemizedlist>
23<listitem>
24<para>You can make branch from a commit of your local <command>nixos-version</command>. That will help you to avoid additional local compilations. Because you will receive packages from binary cache.
25
26<itemizedlist>
27<listitem>
28<para>For example: <command>nixos-version</command> returns <command>15.05.git.0998212 (Dingo)</command>. So you can do:</para>
29</listitem>
30</itemizedlist>
31
32<screen>
33$ git checkout 0998212
34$ git checkout -b 'fix/pkg-name-update'
35</screen>
36</para>
37</listitem>
38
39<listitem>
40<para>Please avoid working directly on the <command>master</command> branch.</para>
41</listitem>
42</itemizedlist>
43</para>
44</listitem>
45
46<listitem>
47<para>Make commits of logical units.
48
49<itemizedlist>
50<listitem>
51<para>If you removed pkgs, made some major NixOS changes etc., write about them in <command>nixos/doc/manual/release-notes/rl-unstable.xml</command>.</para>
52</listitem>
53</itemizedlist>
54</para>
55</listitem>
56
57<listitem>
58<para>Check for unnecessary whitespace with <command>git diff --check</command> before committing.</para>
59</listitem>
60
61<listitem>
62<para>Format the commit in a following way:</para>
63<programlisting>
64(pkg-name | service-name): (from -> to | init at version | refactor | etc)
65Additional information.
66</programlisting>
67
68<itemizedlist>
69<listitem>
70<para>Examples:
71
72<itemizedlist>
73<listitem>
74<para>
75<command>nginx: init at 2.0.1</command>
76</para>
77</listitem>
78
79<listitem>
80<para>
81<command>firefox: 3.0 -> 3.1.1</command>
82</para>
83</listitem>
84
85<listitem>
86<para>
87<command>hydra service: add bazBaz option</command>
88</para>
89</listitem>
90
91<listitem>
92<para>
93<command>nginx service: refactor config generation</command>
94</para>
95</listitem>
96</itemizedlist>
97</para>
98</listitem>
99</itemizedlist>
100</listitem>
101
102<listitem>
103<para>Test your changes. If you work with
104
105<itemizedlist>
106<listitem>
107<para>nixpkgs:
108
109<itemizedlist>
110<listitem>
111<para>update pkg ->
112
113<itemizedlist>
114<listitem>
115<para>
116<command>nix-env -i pkg-name -f <path to your local nixpkgs folder></command>
117</para>
118</listitem>
119</itemizedlist>
120</para>
121</listitem>
122
123<listitem>
124<para>add pkg ->
125
126<itemizedlist>
127<listitem>
128<para>Make sure it's in <command>pkgs/top-level/all-packages.nix</command>
129</para>
130</listitem>
131
132<listitem>
133<para>
134<command>nix-env -i pkg-name -f <path to your local nixpkgs folder></command>
135</para>
136</listitem>
137</itemizedlist>
138</para>
139</listitem>
140
141<listitem>
142<para>
143<emphasis>If you don't want to install pkg in you profile</emphasis>.
144
145<itemizedlist>
146<listitem>
147<para>
148<command>nix-build -A pkg-attribute-name <path to your local nixpkgs folder>/default.nix</command> and check results in the folder <command>result</command>. It will appear in the same directory where you did <command>nix-build</command>.</para>
149</listitem>
150</itemizedlist>
151</para>
152</listitem>
153
154<listitem>
155<para>If you did <command>nix-env -i pkg-name</command> you can do <command>nix-env -e pkg-name</command> to uninstall it from your system.</para>
156</listitem>
157</itemizedlist>
158</para>
159</listitem>
160
161<listitem>
162<para>NixOS and its modules:
163
164<itemizedlist>
165<listitem>
166<para>You can add new module to your NixOS configuration file (usually it's <command>/etc/nixos/configuration.nix</command>).
167 And do <command>sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast</command>.</para>
168</listitem>
169</itemizedlist>
170</para>
171</listitem>
172</itemizedlist>
173</para>
174</listitem>
175
176<listitem>
177<para>If you have commits <command>pkg-name: oh, forgot to insert whitespace</command>: squash commits in this case. Use <command>git rebase -i</command>.</para>
178</listitem>
179
180<listitem>
181<para>Rebase you branch against current <command>master</command>.</para>
182</listitem>
183</itemizedlist>
184</section>
185
186<section>
187<title>Submitting changes</title>
188
189<itemizedlist>
190<listitem>
191<para>Push your changes to your fork of nixpkgs.</para>
192</listitem>
193
194<listitem>
195<para>Create pull request:
196
197<itemizedlist>
198<listitem>
199<para>Write the title in format <command>(pkg-name | service): improvement</command>.
200
201<itemizedlist>
202<listitem>
203<para>If you update the pkg, write versions <command>from -> to</command>.</para>
204</listitem>
205</itemizedlist>
206</para>
207</listitem>
208
209<listitem>
210<para>Write in comment if you have tested your patch. Do not rely much on <command>TravisCI</command>.</para>
211</listitem>
212
213<listitem>
214<para>If you make an improvement, write about your motivation.</para>
215</listitem>
216
217<listitem>
218<para>Notify maintainers of the package. For example add to the message: <command>cc @jagajaga @domenkozar</command>.</para>
219</listitem>
220</itemizedlist>
221</para>
222</listitem>
223</itemizedlist>
224</section>
225
226<section>
227 <title>Pull Request Template</title>
228 <para>
229 The pull request template helps determine what steps have been made for a
230 contribution so far, and will help guide maintainers on the status of a
231 change. The motivation section of the PR should include any extra details
232 the title does not address and link any existing issues related to the pull
233 request.
234 </para>
235 <para>When a PR is created, it will be pre-populated with some checkboxes detailed below:
236 </para>
237 <section>
238 <title>Tested using sandboxing</title>
239 <para>
240 When sandbox builds are enabled, Nix will setup an isolated environment
241 for each build process. It is used to remove further hidden dependencies
242 set by the build environment to improve reproducibility. This includes
243 access to the network during the build outside of
244 <function>fetch*</function> functions and files outside the Nix store.
245 Depending on the operating system access to other resources are blocked
246 as well (ex. inter process communication is isolated on Linux); see <link
247 xlink:href="https://nixos.org/nix/manual/#description-45">build-use-sandbox</link>
248 in Nix manual for details.
249 </para>
250 <para>
251 Sandboxing is not enabled by default in Nix due to a small performance
252 hit on each build. In pull requests for <link
253 xlink:href="https://github.com/NixOS/nixpkgs/">nixpkgs</link> people
254 are asked to test builds with sandboxing enabled (see <literal>Tested
255 using sandboxing</literal> in the pull request template) because
256 in<link
257 xlink:href="https://nixos.org/hydra/">https://nixos.org/hydra/</link>
258 sandboxing is also used.
259 </para>
260 <para>
261 Depending if you use NixOS or other platforms you can use one of the
262 following methods to enable sandboxing <emphasis role="bold">before</emphasis> building the package:
263 <itemizedlist>
264 <listitem>
265 <para>
266 <emphasis role="bold">Globally enable sandboxing on NixOS</emphasis>:
267 add the following to
268 <filename>configuration.nix</filename>
269 <screen>nix.useSandbox = true;</screen>
270 </para>
271 </listitem>
272 <listitem>
273 <para>
274 <emphasis role="bold">Globally enable sandboxing on non-NixOS platforms</emphasis>:
275 add the following to: <filename>/etc/nix/nix.conf</filename>
276 <screen>build-use-sandbox = true</screen>
277 </para>
278 </listitem>
279 </itemizedlist>
280 </para>
281
282 </section>
283 <section>
284 <title>Built on platform(s)</title>
285 <para>
286 Many Nix packages are designed to run on multiple
287 platforms. As such, it's important to let the maintainer know which
288 platforms your changes have been tested on. It's not always practical to
289 test a change on all platforms, and is not required for a pull request to
290 be merged. Only check the systems you tested the build on in this
291 section.
292 </para>
293 </section>
294 <section>
295 <title>Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)</title>
296 <para>
297 Packages with automated tests are much more likely to be merged in a
298 timely fashion because it doesn't require as much manual testing by the
299 maintainer to verify the functionality of the package. If there are
300 existing tests for the package, they should be run to verify your changes
301 do not break the tests. Tests only apply to packages with NixOS modules
302 defined and can only be run on Linux. For more details on writing and
303 running tests, see the <link
304 xlink:href="https://nixos.org/nixos/manual/index.html#sec-nixos-tests">section
305 in the NixOS manual</link>.
306 </para>
307 </section>
308 <section>
309 <title>Tested compilation of all pkgs that depend on this change using <command>nox-review</command></title>
310 <para>
311 If you are updating a package's version, you can use nox to make sure all
312 packages that depend on the updated package still compile correctly. This
313 can be done using the nox utility. The <command>nox-review</command>
314 utility can look for and build all dependencies either based on
315 uncommited changes with the <literal>wip</literal> option or specifying a
316 github pull request number.
317 </para>
318 <para>
319 review uncommitted changes:
320 <screen>nix-shell -p nox --run nox-review wip</screen>
321 </para>
322 <para>
323 review changes from pull request number 12345:
324 <screen>nix-shell -p nox --run nox-review pr 12345</screen>
325 </para>
326 </section>
327 <section>
328 <title>Tested execution of all binary files (usually in <filename>./result/bin/</filename>)</title>
329 <para>
330 It's important to test any executables generated by a build when you
331 change or create a package in nixpkgs. This can be done by looking in
332 <filename>./result/bin</filename> and running any files in there, or at a
333 minimum, the main executable for the package. For example, if you make a change
334 to <package>texlive</package>, you probably would only check the binaries
335 associated with the change you made rather than testing all of them.
336 </para>
337 </section>
338 <section>
339 <title>Meets nixpkgs contribution standards</title>
340 <para>
341 The last checkbox is fits <link
342 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/.github/CONTRIBUTING.md">CONTRIBUTING.md</link>.
343 The contributing document has detailed information on standards the Nix
344 community has for commit messages, reviews, licensing of contributions
345 you make to the project, etc... Everyone should read and understand the
346 standards the community has for contributing before submitting a pull
347 request.
348 </para>
349
350 </section>
351</section>
352
353<section>
354<title>Hotfixing pull requests</title>
355
356<itemizedlist>
357<listitem>
358<para>Make the appropriate changes in you branch.</para>
359</listitem>
360
361<listitem>
362<para>Don't create additional commits, do
363
364<itemizedlist>
365<listitem>
366<para><command>git rebase -i</command></para>
367</listitem>
368<listitem>
369<para>
370<command>git push --force</command> to your branch.</para>
371</listitem>
372</itemizedlist>
373</para>
374</listitem>
375
376</itemizedlist>
377</section>
378
379<section>
380<title>Commit policy</title>
381
382<itemizedlist>
383<listitem>
384<para>Commits must be sufficiently tested before being merged, both for the master and staging branches.</para>
385</listitem>
386
387<listitem>
388<para>Hydra builds for master and staging should not be used as testing platform, it's a build farm for changes that have been already tested.</para>
389</listitem>
390
391<listitem>
392<para>When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people's installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from @edolstra.</para>
393</listitem>
394</itemizedlist>
395
396<section>
397 <title>Master branch</title>
398
399 <itemizedlist>
400 <listitem>
401 <para>
402 It should only see non-breaking commits that do not cause mass rebuilds.
403 </para>
404 </listitem>
405 </itemizedlist>
406</section>
407
408<section>
409 <title>Staging branch</title>
410
411 <itemizedlist>
412 <listitem>
413 <para>
414 It's only for non-breaking mass-rebuild commits. That means it's not to
415 be used for testing, and changes must have been well tested already.
416 <link xlink:href="http://comments.gmane.org/gmane.linux.distributions.nixos/13447">Read policy here</link>.
417 </para>
418 </listitem>
419 <listitem>
420 <para>
421 If the branch is already in a broken state, please refrain from adding
422 extra new breakages. Stabilize it for a few days, merge into master,
423 then resume development on staging.
424 <link xlink:href="http://hydra.nixos.org/jobset/nixpkgs/staging#tabs-evaluations">Keep an eye on the staging evaluations here</link>.
425 If any fixes for staging happen to be already in master, then master can
426 be merged into staging.
427 </para>
428 </listitem>
429 </itemizedlist>
430</section>
431
432<section>
433 <title>Stable release branches</title>
434
435 <itemizedlist>
436 <listitem>
437 <para>
438 If you're cherry-picking a commit to a stable release branch, always use
439 <command>git cherry-pick -xe</command> and ensure the message contains a
440 clear description about why this needs to be included in the stable
441 branch.
442 </para>
443 <para>An example of a cherry-picked commit would look like this:</para>
444 <screen>
445nixos: Refactor the world.
446
447The original commit message describing the reason why the world was torn apart.
448
449(cherry picked from commit abcdef)
450Reason: I just had a gut feeling that this would also be wanted by people from
451the stone age.
452 </screen>
453 </listitem>
454 </itemizedlist>
455</section>
456
457</section>
458</chapter>
459