@@ -94,7 +94,19 @@ You can try this when you notice that a package has been updated. You
9494can also periodically try to lift bounds (I think it's good to do this
9595at the start of your week /@bergmark)
9696
97−If stackage-curator is happy commit the change ("Remove upper bounds and close #X").
97+If not all packages have been updated check if any of them are missing
98+from the original issue and if so add a new comment mentioning them. A
99+new package may appear if its dependencies were part of this issue but
100+have been updated since the last time we checked. We want to give
101+these new packages ample time to be upgraded.
102+
103+If stackage-curator is happy commit the change ("Remove upper bounds
104+and close #X"). After doing this the next nightly build may fail
105+because some packages didn't have an upper bound in place, but
106+compilation failed. In this case revert the previous commit so any
107+disabled packages are enabled again, re-open the issue, and add a new
108+comment with the failing packages. This is to give all maintainers
109+enough time to upgrade for this case as well.
98110
99111### Amending upper bounds
100112
@@ -154,9 +166,12 @@ Comment out the offending packages from the "packages" section and add
154166a comment saying why it was disabled:
155167
156168```
157− # - swagger # BLOCKED aeson 1.0
169+ # - swagger # bounds: aeson 1.0
158170```
159171
172+If this causes reverse dependencies to be disabled we should notify
173+the maintainers of those packages.
174+
160175
161176## Updating the content of the Docker image used for building
162177
@@ -277,26 +292,46 @@ You can wipe the nightly cache and rebuild everything by doing
277292`rm -rf /var/stackage/stackage/automated/nightly`.
278293Replace nightly with `lts7` to wipe the LTS 7 cache.
279294
295+### Force a single package rebuild
296+
297+You can force a single package to rebuild by deleting its "previous result"
298+file, e.g.:
299+
300+```
301+$ rm /var/stackage/stackage/automated/nightly/work/builds/nightly/prevres/Build/cryptohash-0.11.9
302+```
303+
280304## Local curator setup
281305
282306We do not run the full stackage build locally as that might take too
283−much time. Some steps on the other hand are much faster to do
284−yourself.
285−
286−It is useful to be able to modify constraints locally before pushing to
287−the repository. To do this first install stackage-curator:
288−`git clone git@github.com:fpco/stackage-curator.git && cd stackage-curator && stack install`
289−or get the linux binary: https://s3.amazonaws.com/stackage-travis/stackage-curator/stackage-curator.bz2
290−(it is a good idea to upgrade stackage-curator at least at the start of your week as curator).
291−Then clone the stackage repo `git clone git@github.com:fpco/stackage.git`.
292−Inside it run `stack update && stackage-curator check` to get new packages and do dependency resolution.
293−
294−This can be used to make sure all version bounds are in place
295−(including for test suites and benchmarks), to check whether bounds
296−can be lifted, and to get `tell-me-when-its-released` notifications.
297−
298−Notably this does not build anything, so you wont see any compilation
299−errors for builds/tests/benchmarks.
307+much time. However, some steps on the other hand are much faster to do
308+yourself, e.g. verifying constraints without building anything.
309+
310+To get started, install `stackage-curator` via Git, or [the Linux binary]:
311+
312+```
313+$ git clone git@github.com:fpco/stackage-curator.git
314+$ cd stackage-curator && stack install
315+```
316+
317+It is a good idea to upgrade `stackage-curator` at the start of your week.
318+Then, clone the stackage repo, get the latest packages and run dependency
319+resolution:
320+
321+```
322+$ git clone git@github.com:fpco/stackage.git
323+$ stack update && stackage-curator check
324+```
325+
326+This can be used to make sure all version bounds are in place, including for
327+test suites and benchmarks, to check whether bounds can be lifted, and to get
328+[tell-me-when-its-released] notifications.
329+
330+`stackage-curator` does not build anything, so you wont see any compilation
331+errors for builds, tests and benchmarks.
332+
333+[the Linux binary]: https://s3.amazonaws.com/stackage-travis/stackage-curator/stackage-curator.bz2
334+[tell-me-when-its-released]: https://github.com/fpco/stackage/blob/master/CURATORS.md#waiting-for-new-releases
300335
301336## Adding new curators
302337