···

       
7
       
 
       
the Nixpkgs `master` branch.

     

       
8
       
 
       


     

       
9
       
 
       
We do this by periodically merging an updated set of Haskell packages on the

     

       
10
       
-
       
`haskell-updates` branch into the `master` branch.  Each member of the team

     

       
11
       
 
       
takes a two week period where they are in charge of merging the

     

       
12
       
-
       
`haskell-updates` branch into `master`.  This is the documentation for this

     

       
13
       
 
       
workflow.

     

       
14
       
 
       


     

       
15
       
 
       
The workflow generally proceeds in three main steps:

     

       
16
       
 
       


     

       
17
       
 
       
1. create the initial `haskell-updates` PR, and update Stackage and Hackage snapshots

     

       
18
       
 
       
1. wait for contributors to fix newly broken Haskell packages

     

       
19
       
-
       
1. merge `haskell-updates` into `master`

     

       
20
       
 
       


     

       
21
       
 
       
Each of these steps is described in a separate section.

     

       
22
       
 
       


     

       
23
       
 
       
There is a script that automates the workflow for merging the currently open

     

       
24
       
-
       
`haskell-updates` PR into `master` and opening the next PR.  It is described

     

       
25
       
 
       
at the end of this document.

     

       
26
       
 
       


     

       
27
       
 
       
## Initial `haskell-updates` PR

     

       
28
       
 
       


     

       
29
       
-
       
In this section we create the PR for merging `haskell-updates` into `master`.

     

       
30
       
 
       


     

       
31
       
-
       
1.  Make sure the `haskell-updates` branch is up-to-date with `master`.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
32
       
 
       


     

       
33
       
 
       
1.  Update the Stackage Nightly resolver used by Nixpkgs and create a commit:

     

       
34
       
 
       


     
···

       
50
       
 
       


     

       
51
       
 
       
1.  Push these commits to the `haskell-updates` branch of the NixOS/nixpkgs repository.

     

       
52
       
 
       


     

       
53
       
-
       
1.  Open a PR on Nixpkgs for merging `haskell-updates` into `master`.  The recommended

     

       
54
       
 
       
    PR title and body text are described in the `merge-and-open-pr.sh` section.

     

       
55
       
 
       


     

       
56
       
 
       
## Notify Maintainers and Fix Broken Packages

     
···

       
85
       
 
       


     

       
86
       
 
       
Maintainers should be given at least 7 days to fix up their packages when they

     

       
87
       
 
       
break.  If maintainers don't fix up their packages within 7 days, then they

     

       
88
       
-
       
may be marked broken before merging `haskell-updates` into `master`.

     

       
89
       
 
       


     

       
90
       
 
       
### Fix Broken Packages

     

       
91
       
 
       


     
···

       
153
       
 
       


     

       
154
       
 
       
-   All updated files will be committed.

     

       
155
       
 
       


     

       
156
       
-
       
## Merge `haskell-updates` into `master`

     

       
157
       
 
       


     

       
158
       
 
       
Now it is time to merge the `haskell-updates` PR you opened above.

     

       
159
       
 
       


     
···

       
168
       
 
       
    have been pinged on GitHub and given at least a week to fix their packages.

     

       
169
       
 
       
    This is especially important for widely-used packages like `cachix`.

     

       
170
       
 
       


     

       
171
       
-
       
-   Make sure you first merge the `master` branch into `haskell-updates`.  Wait

     

       
172
       
-
       
    for Hydra to evaluate the new `haskell-updates` jobset.  Make sure you only

     

       
173
       
-
       
    merge `haskell-updates` into `master` when there are no evaluation errors.

     

       
174
       
-
       


     

       
175
       
-
       
-   Due to Hydra having only a small number of Darwin build machines, the

     

       
176
       
-
       
    `haskell-updates` jobset on Hydra often has many queued Darwin jobs.

     

       
177
       
-
       
    In order to not have these queued Darwin jobs prevent the `haskell-updates`

     

       
178
       
-
       
    branch from being merged to `master` in a timely manner, we have special

     

       
179
       
-
       
    rules for Darwin jobs.

     

       
180
       
-
       


     

       
181
       
-
       
    -   It is alright to merge the `haskell-updates` branch to `master` if

     

       
182
       
-
       
        there are remaining queued Darwin jobs on Hydra.

     

       
183
       
-
       


     

       
184
       
-
       
    -   We would like to keep GHC and the `mergeable` job building on Darwin.

     

       
185
       
-
       
        Do not merge the `haskell-updates` branch to `master` if GHC is failing

     

       
186
       
-
       
        to build, or the `mergeable` job has failing Darwin constituent jobs.

     

       
187
       
-
       


     

       
188
       
-
       
        If GHC and the `mergeable` job are not failing, but merely queued,

     

       
189
       
-
       
        it is alright to merge the `haskell-updates` branch to `master`.

     

       
190
       
-
       


     

       
191
       
-
       
    -   We do not need to keep the `maintained` job building on Darwin.

     

       
192
       
-
       
        If `maintained` packages are failing on Darwin, it is helpful to

     

       
193
       
-
       
        mark them as broken on that platform.

     

       
194
       
 
       


     

       
195
       
 
       
## Script for Merging `haskell-updates` and Opening a New PR

     

       
196
       
 
       


     
···

       
229
       
 
       
    $ ./maintainers/scripts/haskell/mark-broken.sh --do-commit

     

       
230
       
 
       
    ```

     

       
231
       
 
       


     

       
232
       
-
       
1.  Merge `master` into `haskell-updates` and make sure to push to the

     

       
233
       
-
       
    `haskell-updates` branch.  (This can be skipped if `master` has recently

     

       
234
       
-
       
    been merged into `haskell-updates`.)

     

       
235
       
-
       


     

       
236
       
 
       
1.  Go to https://hydra.nixos.org/jobset/nixpkgs/haskell-updates and force an

     

       
237
       
 
       
    evaluation of the `haskell-updates` jobset.  See one of the following

     

       
238
       
 
       
    sections for how to do this.  Make sure there are no evaluation errors.  If

     
···

       
266
       
 
       


     

       
267
       
 
       
## Update Hackage Version Information

     

       
268
       
 
       


     

       
269
       
-
       
After merging into `master` you can update what Hackage displays as the current

     

       
270
       
 
       
version in NixOS for every individual package.  To do this you run

     

       
271
       
-
       
`maintainers/scripts/haskell/upload-nixos-package-list-to-hackage.sh`.  See the

     

       
272
       
-
       
script for how to provide credentials. Once you have configured credentials,

     

       
273
       
-
       
running this takes only a few seconds.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
274
       
 
       


     

       
275
       
 
       
## Additional Info

     

       
276
       
 
       


     

···

       
7
       
 
       
the Nixpkgs `master` branch.

     

       
8
       
 
       


     

       
9
       
 
       
We do this by periodically merging an updated set of Haskell packages on the

     

       
10
       
+
       
`haskell-updates` branch into the `staging` branch.  Each member of the team

     

       
11
       
 
       
takes a two week period where they are in charge of merging the

     

       
12
       
+
       
`haskell-updates` branch into `staging`.  This is the documentation for this

     

       
13
       
 
       
workflow.

     

       
14
       
 
       


     

       
15
       
 
       
The workflow generally proceeds in three main steps:

     

       
16
       
 
       


     

       
17
       
 
       
1. create the initial `haskell-updates` PR, and update Stackage and Hackage snapshots

     

       
18
       
 
       
1. wait for contributors to fix newly broken Haskell packages

     

       
19
       
+
       
1. merge `haskell-updates` into `staging`

     

       
20
       
 
       


     

       
21
       
 
       
Each of these steps is described in a separate section.

     

       
22
       
 
       


     

       
23
       
 
       
There is a script that automates the workflow for merging the currently open

     

       
24
       
+
       
`haskell-updates` PR into `staging` and opening the next PR.  It is described

     

       
25
       
 
       
at the end of this document.

     

       
26
       
 
       


     

       
27
       
 
       
## Initial `haskell-updates` PR

     

       
28
       
 
       


     

       
29
       
+
       
In this section we create the PR for merging `haskell-updates` into `staging`.

     

       
30
       
 
       


     

       
31
       
+
       
1.  Make sure the `haskell-updates` branch is up-to-date with a _merge base_ of

     

       
32
       
+
       
    `staging` and `master`. `haskell-updates` is not based _on_ `staging`,

     

       
33
       
+
       
    so that it can share binary cache with `master`.

     

       
34
       
 
       


     

       
35
       
 
       
1.  Update the Stackage Nightly resolver used by Nixpkgs and create a commit:

     

       
36
       
 
       


     
···

       
52
       
 
       


     

       
53
       
 
       
1.  Push these commits to the `haskell-updates` branch of the NixOS/nixpkgs repository.

     

       
54
       
 
       


     

       
55
       
+
       
1.  Open a PR on Nixpkgs for merging `haskell-updates` into `staging`.  The recommended

     

       
56
       
 
       
    PR title and body text are described in the `merge-and-open-pr.sh` section.

     

       
57
       
 
       


     

       
58
       
 
       
## Notify Maintainers and Fix Broken Packages

     
···

       
87
       
 
       


     

       
88
       
 
       
Maintainers should be given at least 7 days to fix up their packages when they

     

       
89
       
 
       
break.  If maintainers don't fix up their packages within 7 days, then they

     

       
90
       
+
       
may be marked broken before merging `haskell-updates` into `staging`.

     

       
91
       
 
       


     

       
92
       
 
       
### Fix Broken Packages

     

       
93
       
 
       


     
···

       
155
       
 
       


     

       
156
       
 
       
-   All updated files will be committed.

     

       
157
       
 
       


     

       
158
       
+
       
## Merge `haskell-updates` into `staging`

     

       
159
       
 
       


     

       
160
       
 
       
Now it is time to merge the `haskell-updates` PR you opened above.

     

       
161
       
 
       


     
···

       
170
       
 
       
    have been pinged on GitHub and given at least a week to fix their packages.

     

       
171
       
 
       
    This is especially important for widely-used packages like `cachix`.

     

       
172
       
 
       


     

       
173
       
+
       
-   Keep an eye on the next `staging-next` iteration (which is branched off

     

       
174
       
+
       
    from `staging`) to confirm that there are no show stopping issues stemming

     

       
175
       
+
       
    from interactions between changes on `staging` and `haskell-updates`.

     

       
176
       
+
       
    Also be aware that build or eval regressions from a `haskell-updates`

     

       
177
       
+
       
    iteration may only become apparent on `staging-next`, especially when the

     

       
178
       
+
       
    `haskell-updates` jobset had e.g. Darwin builds disabled.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
179
       
 
       


     

       
180
       
 
       
## Script for Merging `haskell-updates` and Opening a New PR

     

       
181
       
 
       


     
···

       
214
       
 
       
    $ ./maintainers/scripts/haskell/mark-broken.sh --do-commit

     

       
215
       
 
       
    ```

     

       
216
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
217
       
 
       
1.  Go to https://hydra.nixos.org/jobset/nixpkgs/haskell-updates and force an

     

       
218
       
 
       
    evaluation of the `haskell-updates` jobset.  See one of the following

     

       
219
       
 
       
    sections for how to do this.  Make sure there are no evaluation errors.  If

     
···

       
247
       
 
       


     

       
248
       
 
       
## Update Hackage Version Information

     

       
249
       
 
       


     

       
250
       
+
       
Remember to regularly update what Hackage displays as the current

     

       
251
       
 
       
version in NixOS for every individual package.  To do this you run

     

       
252
       
+
       
`maintainers/scripts/haskell/upload-nixos-package-list-to-hackage.sh` on a checkout

     

       
253
       
+
       
of `master` (or `nixpkgs-unstable`).  See the script for how to provide credentials.

     

       
254
       
+
       
Once you have configured credentials, running this takes only a few seconds.

     

       
255
       
+
       


     

       
256
       
+
       
The best time to do this is after `staging-next` has been merged since this is

     

       
257
       
+
       
the way Haskell package updates propagate to `master`.

     

       
258
       
 
       


     

       
259
       
 
       
## Additional Info

     

       
260