···

       
214
       
214
       
 
       
- 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.

     

       
215
       
215
       
 
       
- 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.

     

       
216
       
216
       
 
       


     

       
217
       
217
       
-
       
### Branches {#submitting-changes-branches}

     

       
218
       
218
       
-
       


     

       
219
       
219
       
-
       
The `nixpkgs` repository has three major branches:

     

       
220
       
220
       
-
       
- `master`

     

       
221
       
221
       
-
       
- `staging`

     

       
222
       
222
       
-
       
- `staging-next`

     

       
223
       
223
       
-
       


     

       
224
       
224
       
-
       
The most important distinction between them is that `staging`

     

       
225
       
225
       
-
       
(colored red in the diagram below) can receive commits which cause

     

       
226
       
226
       
-
       
a mass-rebuild (for example, anything that changes the `drvPath` of

     

       
227
       
227
       
-
       
`stdenv`).  The other two branches `staging-next` and `master`

     

       
228
       
228
       
-
       
(colored green in the diagram below) can *not* receive commits which

     

       
229
       
229
       
-
       
cause a mass-rebuild.

     

       
230
       
230
       
-
       


     

       
231
       
231
       
-
       
Arcs between the branches show possible merges into these branches,

     

       
232
       
232
       
-
       
either from other branches or from independently submitted PRs.  The

     

       
233
       
233
       
-
       
colors of these edges likewise show whether or not they could

     

       
234
       
234
       
-
       
trigger a mass rebuild (red) or must not trigger a mass rebuild

     

       
235
       
235
       
-
       
(green).

     

       
217
       
217
       
+
       
::: {.figure #fig-staging-workflow}

     

       
218
       
218
       
+
       
# Staging workflow

     

       
219
       
219
       
+
       
<!-- generated from ./staging-workflow.dot using: dot -Tsvg staging-workflow.dot > staging-workflow.svg -->

     

       
220
       
220
       
+
       
![Staging workflow](./staging-workflow.svg)

     

       
221
       
221
       
+
       
:::

     

       
236
       
222
       
 
       


     

       
237
       
237
       
-
       
Hydra runs automatic builds for the green branches.

     

       
223
       
223
       
+
       
[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the blue arrows in the diagram above.  The purple arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.

     

       
238
       
224
       
 
       


     

       
239
       
239
       
-
       
Notice that the automatic merges are all green arrows.  This is by

     

       
240
       
240
       
-
       
design.  Any merge which might cause a mass rebuild on a branch

     

       
241
       
241
       
-
       
which has automatic builds (`staging-next`, `master`) will be a

     

       
242
       
242
       
-
       
manual merge to make sure it is good use of compute power.

     

       
243
       
225
       
 
       


     

       
244
       
244
       
-
       
Nixpkgs has two branches so that there is one branch (`staging`)

     

       
245
       
245
       
-
       
which accepts mass-rebuilding commits, and one fast-rebuilding

     

       
246
       
246
       
-
       
branch which accepts independent PRs (`master`).  The `staging-next`

     

       
247
       
247
       
-
       
branch allows the Hydra operators to batch groups of commits to

     

       
248
       
248
       
-
       
`staging` to be built.  By keeping the `staging-next` branch

     

       
249
       
249
       
-
       
separate from `staging`, this batching does not block

     

       
250
       
250
       
-
       
developers from merging changes into `staging`.

     

       
251
       
251
       
-
       


     

       
252
       
252
       
-
       
```{.graphviz caption="Staging workflow"}

     

       
253
       
253
       
-
       
digraph {

     

       
254
       
254
       
-
       
    master [color="green" fontcolor=green]

     

       
255
       
255
       
-
       
    "staging-next" [color="green" fontcolor=green]

     

       
256
       
256
       
-
       
    staging [color="red" fontcolor=red]

     

       
257
       
257
       
-
       


     

       
258
       
258
       
-
       
    "small changes" [fontcolor=green shape=none]

     

       
259
       
259
       
-
       
    "small changes" -> master [color=green]

     

       
260
       
260
       
-
       


     

       
261
       
261
       
-
       
    "mass-rebuilds and other large changes" [fontcolor=red shape=none]

     

       
262
       
262
       
-
       
    "mass-rebuilds and other large changes" -> staging [color=red]

     

       
263
       
263
       
-
       


     

       
264
       
264
       
-
       
    "critical security fixes" [fontcolor=green shape=none]

     

       
265
       
265
       
-
       
    "critical security fixes" -> master [color=green]

     

       
266
       
266
       
-
       


     

       
267
       
267
       
-
       
    "staging fixes which do not cause staging to mass-rebuild" [fontcolor=green shape=none]

     

       
268
       
268
       
-
       
    "staging fixes which do not cause staging to mass-rebuild" -> "staging-next" [color=green]

     

       
269
       
269
       
-
       


     

       
270
       
270
       
-
       
    "staging-next" -> master [color="red"] [label="manual merge"] [fontcolor="red"]

     

       
271
       
271
       
-
       
    "staging" -> "staging-next" [color="red"] [label="manual merge"] [fontcolor="red"]

     

       
272
       
272
       
-
       


     

       
273
       
273
       
-
       
    master -> "staging-next" [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]

     

       
274
       
274
       
-
       
    "staging-next" -> staging [color="green"] [label="automatic merge (GitHub Action)"] [fontcolor="green"]

     

       
275
       
275
       
-
       
}

     

       
276
       
276
       
-
       
```

     

       
277
       
277
       
-
       


     

       
278
       
278
       
-
       
[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours; these are the green arrows in the diagram above.  The red arrows in the diagram above are done manually and much less frequently.  You can get an idea of how often these merges occur by looking at the git history.

     

       
279
       
279
       
-
       


     

       
280
       
280
       
-
       


     

       
281
       
281
       
-
       
#### Master branch {#submitting-changes-master-branch}

     

       
226
       
226
       
+
       
### Master branch {#submitting-changes-master-branch}

     

       
282
       
227
       
 
       


     

       
283
       
228
       
 
       
The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.

     

       
284
       
229
       
 
       


     

       
285
       
285
       
-
       
#### Staging branch {#submitting-changes-staging-branch}

     

       
230
       
230
       
+
       
### Staging branch {#submitting-changes-staging-branch}

     

       
286
       
231
       
 
       


     

       
287
       
232
       
 
       
The `staging` branch is a development branch where mass-rebuilds go. Mass rebuilds are commits that cause rebuilds for many packages, like more than 500 (or perhaps, if it's 'light' packages, 1000). It should only see non-breaking mass-rebuild commits. That means it is not to be used for testing, and changes must have been well tested already. If the branch is already in a broken state, please refrain from adding extra new breakages.

     

       
288
       
233
       
 
       


     

       
289
       
234
       
 
       
During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.

     

       
290
       
235
       
 
       


     

       
291
       
291
       
-
       
#### Staging-next branch {#submitting-changes-staging-next-branch}

     

       
236
       
236
       
+
       
### Staging-next branch {#submitting-changes-staging-next-branch}

     

       
292
       
237
       
 
       


     

       
293
       
238
       
 
       
The `staging-next` branch is for stabilizing mass-rebuilds submitted to the `staging` branch prior to merging them into `master`. Mass-rebuilds must go via the `staging` branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the `master` branch.

     

       
294
       
239
       
 
       


     
···

       
296
       
241
       
 
       


     

       
297
       
242
       
 
       
During the process of a releasing a new NixOS version, this branch or the release-critical packages can be restricted to non-breaking changes.

     

       
298
       
243
       
 
       


     

       
299
       
299
       
-
       
#### Stable release branches {#submitting-changes-stable-release-branches}

     

       
244
       
244
       
+
       
### Stable release branches {#submitting-changes-stable-release-branches}

     

       
300
       
245
       
 
       


     

       
301
       
246
       
 
       
The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.

     

       
302
       
247