-
Notifications
You must be signed in to change notification settings - Fork 395
Release process
Etienne Millon edited this page Jan 5, 2024
·
2 revisions
This document explains how we release dune. Its goal is to describe how things are done in practice, not discuss how they should be done. There are two aspects to this:
- a fairly rigid flowchart-style process for each type of release
- a softer "decision" section that explains what should inform the decisions to take when there is a manual call to make.
gitGraph
commit id: "feat(1)"
commit id: "feat(2)"
commit id: "feat(3)"
branch "x.y"
commit tag: "x.y.0~alpha1"
checkout main
commit id: "fix(1)"
checkout "x.y"
cherry-pick id: "fix(1)"
commit tag: "x.y.0~alpha2"
commit tag: "x.y.0"
stateDiagram-v2
direction LR
[*] --> Prepare
Prepare --> Alpha
Alpha --> Alpha
Alpha --> Release
Release --> PostRelease
PostRelease --> [*]
-
Prepare:
- Open tracking issue with expected branching date
- List (and update) known blockers. These prevent releasing
x.y.0
- Add "All x.y.z changelogs merged" as blocker
- Add "Mirage test" as blocker (manual workflow should be triggered on a alpha release)
-
Alpha time:
- Branch setup:
- (for N=0) create
x.y
branch
- (for N=0) create
- Prepare alpha release:
- cherry-pick extra commits from
main
(if any) - prepare changelog (ensure version is
x.y.0~alphaN
) make opam-release
- mark opam-repo PR as draft
- cherry-pick extra commits from
- Wait for
opam-repo-ci
- Triage phase:
- consider new failures comparing from latest "known good" release
- ignore transient errors (disk full, switch disconnected, cancelled, etc)
- file issues about regressions, add them to known blockers
- Release Go/No Go (go to Release, or need another alpha)
- Mark alpha PR as closed
- Branch setup:
-
Release time:
- check versioned behaviors are relative to x.y
- On release branch, prepare changelog (merge alpha entries, set header with version)
- Open a PR
prepare-x.y.0
- Self-merge
-
make opam-release
from updated main - Triage
- In case of regression:
- mitigate (for example if this happens on a single OS, set
available
appropriately) - prepare point release
- in the worst case, the release can be cancelled completely and only come in a point release.
- mitigate (for example if this happens on a single OS, set
-
Post-release:
- Categorize changelog entries into Added / Fixed / Changed / Removed / Deprecated
- Open PR on
ocaml/ocaml.org
to add a file in underdata/changelog/dune
- Post to discuss
- Close release milestone
- Close tracking issue
gitGraph
commit tag: "x.y.0"
commit id: "fix(1)"
commit id: "feat(1)"
commit id: "fix(2)"
branch x.y
cherry-pick id: "fix(1)"
cherry-pick id: "fix(2)"
commit tag: "x.y.1"
checkout main
commit id: "feat(2)"
commit id: "feat(3)"
commit id: "fix(3)"
checkout x.y
cherry-pick id: "fix(3)"
commit tag: "x.y.2"
stateDiagram-v2
direction LR
[*] --> Prepare
Prepare --> Backport
Backport --> Backport
Backport --> Release
Release --> PostRelease
PostRelease --> [*]
-
Prepare:
- Create release tracking issue
- List fixes present in main to backport
- Blockers for this release include:
- all backports of listed fixes
- changelogs of previous point releases are merged
-
Backport:
- Branch setup
- (z=1) Create branch
x.y
from commit taggedx.y.0
- (z>1) Position on branch
x.y
- (z=1) Create branch
-
git cherry-pick
commits as merged inmain
- Open PR
- Set
x.y
as target branch, e.g.gh pr create -B x.y
- Title starts with
[x.y]
- List PR in blockers
- Set
- Branch setup
-
Release:
- Position on
x.y
- Prepare changelog
- Open a PR
prepare-x.y.z
make opam-release
- Triage
- Position on
-
Post-release:
- Open PR on
ocaml/ocaml.org
to add a file in underdata/changelog/dune
- Post changelog on Discuss in the same thread as
x.y.0
- Merge changelog
- Close release tracking issue
- Open PR on
-
Release cadence:
- we aim for a minor release roughly every 4 to 6 weeks. More than 8 tends to make riskier releases; less than 3 would be too much overhead.
- we do point releases only for the latest release minor version.
-
Release Go/No Go after alpha:
- the goal is to determine, once the known blockers are fixed, if we need an
alpha(N+1) to get enough confidence about
x.y.0
- downside if release is Go but a bug is found: need a quick point release.
- downside if release is No Go but not bug is found: waste of ~1 day and the ~50k builds.
- the goal is to determine, once the known blockers are fixed, if we need an
alpha(N+1) to get enough confidence about
-
Determine if a change can be backported:
- it needs to be a fix, with no version-specific behaviour
- it needs to be merged in
main
-
Triage:
- The thing to determine is whether a failure is a regression: considering a
failure, would the same build plan succeed with the previous release of Dune?
- Ultimately it's possible to run that locally, for example with
opam build
. - Comparing to the previous release is often enough; but note that some new packages have been added in the meantime.
- Ultimately it's possible to run that locally, for example with
- Transient errors can be ignored or restarted; however some of them like
"solver timed out" can not succeed. Some packages are known to fail in
opam-repo-ci
but there is no good way to skip them. - Sending metadata fixes in
opam-repository
(e.g. OCaml 5 failures) is nice to do but not required.
- The thing to determine is whether a failure is a regression: considering a
failure, would the same build plan succeed with the previous release of Dune?