Second draft

rfcs/0026-staging-workflow.md

@@ -1,9 +1,9 @@
 ---
-feature: (fill me in with a unique ident, my_awesome_feature)
-start-date: (fill me in with today's date, YYYY-MM-DD)
-author: (name of the main author)
-co-authors: (find a buddy later to help our with the RFC)
-related-issues: (will contain links to implementation PRs)
+feature: staging-workflow
+start-date: 2018-03-05
+author: Vladimír Čunát (@vcunat)
+co-authors: Frederik Rietdijk (@FRidh)
+related-issues:
 ---
 
 # Summary
@@ -34,9 +34,9 @@ as possible.
 [design]: #detailed-design
 
 There shall be the following branches:
-- `master` is the main branch and all small deliveries shall go here;
+- `master` is the main branch where all small deliveries go;
 - `staging` is branched from `master` and mass-rebuilds and other large deliveries go to this branch;
-- `staging-next` is branched from `staging` and only fixes to stabilize and security fixes shall be delivered to this branch.
+- `staging-next` is branched from `staging` and only fixes to stabilize and security fixes shall be delivered to this branch. This branch shall be merged into `master` when deemed of sufficiently high quality.
 
 Binary packages shall be build by Hydra for each of these branches. The
 following table gives an overview of the branches, the check interval in hours,
@@ -46,26 +46,46 @@ amount of shares, and the jobset that they build.
 | Branch         | Interval | Shares | Jobset
 |----------------|----------|--------|-----------
 | `master`       | 4        | High   | release.nix
-| `staging`      | 12       | High   | release.nix
-| `staging-next` | 6        | High   | release-small.nix
+| `staging-next` | 12       | Medium | release.nix
+| `staging`      | 6        | Medium | release-small.nix
 
 
-The check interval of `staging` is reduced from 24 hours to 12 hours. This can
-be done because only stabilization fixes shall be submitted and thus fewer
-rebuilds shall typically have to be performed. The `staging-next` shall have a
-short interval of only 6 hours. This is done because of the relatively small
-jobset, and to obtain a higher resolution to detect any troublesome deliveries.
+The check interval of `staging-next` is reduced from 24 hours (the current value
+for `staging`) to 12 hours. This can be done because only stabilization fixes
+shall be submitted and thus fewer rebuilds shall typically have to be performed.
 
+The `staging` branch shall have a short interval of only 6 hours. This is because
+of the relatively small jobset, and to obtain a higher resolution to detect any
+troublesome deliveries.
 
 # Drawbacks
 [drawbacks]: #drawbacks
 
-A potential drawback of this new workflow is that the additional branch may be considered complicated and/or more difficult to work with.
+A potential drawback of this new workflow is that the additional branch may be
+considered complicated and/or more difficult to work with. However, for most
+contributors the workflow will remain the same, that is, choose `master` or
+`staging` depending on the number of rebuilds.
 
 # Alternatives
 [alternatives]: #alternatives
 
-What other designs have been considered? What is the impact of not doing this?
+## Maintain the status quo
+
+The current situation could be kept, however, that would not solve any of the
+issues mentioned in the "Motivation" section.
+
+## Single branch
+
+Instead of multiple branches only a single branch, say `master`, could be kept
+for development. While this removes the issue of merge conflicts, it will result
+in continuous mass-rebuilds on `master`, slowing down the delivery of binary
+substitutes and thus development.
+
+## Reduce Hydra jobset size
+
+Reducing the size of the Hydra jobset would mean the iteration pace could be
+higher, but has the downside of testing fewer packages, and having fewer binary
+substitutes available.
 
 # Unresolved questions
 [unresolved]: #unresolved-questions
@@ -75,4 +95,6 @@ What other designs have been considered? What is the impact of not doing this?
 # Future work
 [future]: #future-work
 
--
+- Document the new workflow;
+- Create the new branch;
+- Create a Hydra jobset for the new branch and adjust the existing jobs`.