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>Hotfixing pull requests</title>
228
229<itemizedlist>
230<listitem>
231<para>Make the appropriate changes in you branch.</para>
232</listitem>
233
234<listitem>
235<para>Don't create additional commits, do
236
237<itemizedlist>
238<listitem>
239<para><command>git rebase -i</command></para>
240</listitem>
241<listitem>
242<para>
243<command>git push --force</command> to your branch.</para>
244</listitem>
245</itemizedlist>
246</para>
247</listitem>
248
249</itemizedlist>
250</section>
251
252<section>
253<title>Commit policy</title>
254
255<itemizedlist>
256<listitem>
257<para>Commits must be sufficiently tested before being merged, both for the master and staging branches.</para>
258</listitem>
259
260<listitem>
261<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>
262</listitem>
263
264<listitem>
265<para>Master should only see non-breaking commits that do not cause mass rebuilds.</para>
266</listitem>
267
268<listitem>
269<para>Staging should only see non-breaking mass-rebuild commits. That means it's not to be used for testing, and changes must have been well tested already. <link xlink:href="http://comments.gmane.org/gmane.linux.distributions.nixos/13447">Read policy here</link>.</para>
270</listitem>
271
272<listitem>
273<para>If staging is already in a broken state, please refrain from adding extra new breakages. Stabilize it for a few days, merge into master, then resume development on staging. <link xlink:href="http://hydra.nixos.org/jobset/nixpkgs/staging#tabs-evaluations">Keep an eye on the staging evaluations here</link>.</para>
274</listitem>
275
276<listitem>
277<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>
278</listitem>
279</itemizedlist>
280
281</section>
282</chapter>
283