Skip to content

chore: update release process documentation #13953

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
shonfeder wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

chore: update release process documentation #13953

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 38 additions & 12 deletions .github/ISSUE_TEMPLATE/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,39 +14,65 @@ assignees: ''
- [ ] Create release candidate branch `X.Y.Z-rc` from last point tag `X.Y.Z-1`
- [ ] Open release draft PR from branch `X.Y.Z-rc` into `main` [link to dune PR]

### Fixes
## Fixes

Regressions requiring fixes in `main` and backports to `X.Y.Z-rc`:

- [ ] #...
- [ ] backported via PR #...
- [ ] #...
- [ ] backported via PR #...

For each PR needing a backport

- Run `VERSION=X.Y.Z PR=<pr-number> ./doc/dev/releases/backport.sh`
- Wait for the PR into the rc branch to pass CI.
- Merge the PR, and record it above, completing the checklist item.

## Release

- [ ] Work thru the [point release process][point-release].
- [ ] opam repo publication PR [link to opam PR]

[point-release]: https://github.com/ocaml/dune/blob/main/doc/dev/releases/process.md#point-releases--patch-releases-xyz-z--0

<!-- } else if MINOR OR MAJOR RELEASE { -->

## Known blockers

Regressions requiring fixes in `main` and backports to the latest version:
Issues blocking the release

- [ ] issue #... blocking the release because of ...
- [ ] backported via PR #...
<!-- } -->
- [ ] resolved by PR #...
- [ ] issue #... blocking the release because of ...
- [ ] resolved by PR #...

## Preparation

To begin once all initial blockers are resolved.

- [ ] Run pre-release CI jobs on `main` branch
- [ ] [mirage](https://github.com/ocaml/dune/actions/workflows/mirage.yml)
- [ ] [packaging](https://github.com/ocaml/dune/actions/workflows/isolated-package-build.yml)
- [ ] Work thru the [pre-release phase](https://github.com/ocaml/dune/blob/main/doc/dev/releases/process.md#pre-release-phase).
Alpha release PRs into opam repo:
- [link to OPAM PR 1]
- [link to OPAM PR 2]
- [ ] Draft PR from the release branch `X.Y.Z-rc` into `main`: [link to dune PR]

## Release

- [ ] Update changelog
<!-- If MINOR OR MAJOR RELEASE: uncomment -->
<!-- - [ ] Create release candidate branch `X.Y.Z-rc` from main -->
<!-- - [ ] Open release draft PR from branch `X.Y.Z-rc` into `main` [link to dune PR] -->
<!-- - [ ] Alpha release PRs into opam repo for triage: -->
<!-- - [link to OPAM PR] -->
<!-- - [ ] Review revdeps diff, and diagnose any new failures -->
- [ ] Work thru the [release phase](https://github.com/ocaml/dune/blob/main/doc/dev/releases/process.md#release-phase).
- [ ] opam repo publication PR [link to opam PR]
<!-- } -->

## Post-release

- [ ] Merge release branch into `main` [link to dune PR]
- [ ] Write a post about the release on Discuss [link to post]
- [ ] Store the revdeps error file in the [logs](https://github.com/ocaml/dune/wiki/Reverse-dependencies-CI-logs) as HTML
<!-- If MINOR OR MAJOR RELEASE: uncomment -->
<!-- - [ ] Increase `lang dune` number -->
<!-- - [ ] Increase the version of Dune to the new latest minor version -->
<!-- - [ ] in the [CI workflow](https://github.com/ocaml/dune/tree/main/ci/workflow.yml.in) -->
<!-- - [ ] in [dune-project](https://github.com/ocaml/dune/blob/main/dune-project#L1) -->
<!-- - [ ] in the [dune-rpc](https://github.com/ocaml/dune/blob/main/otherlibs/dune-rpc/types.ml#L30). -->
163 changes: 83 additions & 80 deletions doc/dev/releases/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,18 @@ aspects to this:
- a softer "decision" section that explains what should inform the decisions to
take when there is a manual call to make.

## Prerequisites

- The latest [dune-release](https://github.com/tarides/dune-release) installed in your dev switch
- A recent version of [github-cli](https://github.com/cli/cli) installed on your system

## Prepare

Open a [release tracking issue][release-issue] and work thru its checklist,
including listing and updating known blockers that are preventing release

[release-issue]: https://github.com/ocaml/dune/issues/new?template=release.md

## Major / Minor Releases (`x.y.0`)

```mermaid
Expand Down Expand Up @@ -39,56 +51,62 @@ stateDiagram-v2
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
- 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
- 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
- compare the new CI revdeps errors with the errors from [previous releases](https://github.com/ocaml/dune/wiki/Reverse-dependencies-CI-logs).
- Release Go/No Go (go to Release, or need another alpha)
- Mark opam alpha PR as closed

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

- Post-release:
- Categorize changelog entries into Added / Fixed / Changed / Removed / Deprecated
- Open PR on `ocaml/ocaml.org` to add a file in under `data/changelog/dune`
- Post to discuss
- Merge changelog
- Increase the version of Dune to the new latest in the [GitHub CI](https://github.com/ocaml/dune/blob/9a274be98cb9c2786dd76184c19c44b89e061ea8/.github/workflows/workflow.yml#L350), [dune-project](https://github.com/ocaml/dune/blob/main/dune-project#L1) and in the [dune-rpc](https://github.com/ocaml/dune/blob/main/otherlibs/dune-rpc/private/types.ml#L30). E.g, if you released `X.Y.Z`, the new version become `X.(Y+1).Z`.
- Update the Dune target in the [nix-ocaml/nix-overlays](https://github.com/nix-ocaml/nix-overlays) (the hash is computed using `nix-prefetch-url --type sha256 <URL>`)
- Close release milestone
- Add the copy of the revdeps file to the [previous releases](https://github.com/ocaml/dune/wiki/Reverse-dependencies-CI-logs) page
- Close tracking issue

## Point Releases / Patch Releases (`x.y.z`, `z >= 0`)
### Pre-release phase

During the pre-release phase, we produce alpha releases, which we use to run the
opam-ci to check for integration with the wider ocaml ecosystem.

1. Create and checkout the release candidate branch `X.Y.Z-rc` from the head of
`main`
2. Let `N=0`
3. Prepare alpha release
- If `N>0`
- Get all regressions fixed in `main`
- Either cherry-pick the fixes from `main` into the rc branch, or create a
new branch off `main`. (This is a judgment call, based on weighing risk of
picking up new regressions vs. the benefits of simpler process and picking
up additional improvements from main.)
- Run pre-release CI jobs on `X.Y.Z-rc` branch
- [mirage](https://github.com/ocaml/dune/actions/workflows/mirage.yml)
- [packaging](https://github.com/ocaml/dune/actions/workflows/isolated-package-build.yml)
- If the pre-release CI detects regreessions, goto (3).
- Build the changelog via `doc/changes/scripts/build_changelog.sh x.y.0~alphaN`
- Review the resulting changelog for intelligibility.
- Commit the changelog update to the release branch with the commit message `[X.Y.Z] prepare alphaN release`
- Run `make opam-release`
- [edit the release][edit-release] to mark it with `Set as a pre-release`
- mark resulting opam-repo PR as a draft
- Wait for the `opam-ci` results
- Review the results:
- Any build or test failures in dune's own packages require fixes
- compare the new CI revdeps errors with the [errors from previous
releases][prev-releases].
- ignore transient errors (disk full, switch disconnected, cancelled, etc)
- If defects are discovered:
- File issues about all regressions, add them to known blockers
- Mark opam alpha PR as closed
- Let `N=N+1` and goto (3)

[edit-release]: https://docs.github.com/en/rest/releases/releases?apiVersion=2026-03-10#update-a-release
[prev-releases]: https://github.com/ocaml/dune/wiki/Reverse-dependencies-CI-logs

### Release phase

- On release branch, prepare changelog
- combine all entries from different alpha release
- set the version header to `X.Y.Z (<date>)`
- commit onto `X.Y.Z-rc` branch with message `[X.Y.Z] release` and push to remote
- Push release branch to remote
- Run `make opam-release` from updated `X.Y.Z-rc` branch
- Add a comment on the opam repo PR linking back to the release tracker issues
and explaining that all triage is completed, and ask the opam repo maintainers
to bypass the opam-ci.
- In case of regression:
- Cancel the minor release publication by closing the opam repo PR
- Mark the GitHub release as a pre-release
- Proceed to a patch release

## Point Releases / Patch Releases (`X.Y.Z`, `Z >= 0`)

```mermaid
gitGraph
Expand Down Expand Up @@ -120,35 +138,21 @@ stateDiagram-v2
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>0) Position on branch `x.y`
- `git cherry-pick` commits as merged in `main`
- Open PR
- Set `x.y` as target branch, e.g. `gh pr create -B x.y`
- Title must be `[x.y] backport #<PR id>`
- List PR in blockers

- Release:
- Position on `x.y`
- Prepare changelog
- Open a PR `prepare-x.y.z`
- `make opam-release`
- Triage

- Post-release:
- Open PR on `ocaml/ocaml.org` to add a file in under `data/changelog/dune`
- Post changelog on Discuss in the same thread as `x.y.0`
- Merge changelog
- Update the Dune target in the [nix-ocaml/nix-overlays](https://github.com/nix-ocaml/nix-overlays) (the hash is computed using `nix-prefetch-url --type sha256 <URL>`)
- Close release tracking issue
- Build the changelog via `doc/changes/scripts/build_changelog.sh X.Y.Z`
- Review the resulting changelog for intelligibility.
- Commit the changelog update to the release branch with the commit message `[X.Y.Z] release`
- Push release branch to remote
- Run `make opam-release`.
- Wait for the `opam-ci` results
- Review the results:
- Any build or test failures in dune's own packages require fixes
- compare the new CI revdeps errors with the [errors from previous releases][prev-releases].
- ignore transient errors (disk full, switch disconnected, cancelled, etc)
- If defects are discovered:
- Close the opam repo PR.
- File issues about all regressions.
- Mark GitHub release as a pre-release.
- Cut a new patch release.

## Decisions

Expand Down Expand Up @@ -180,4 +184,3 @@ stateDiagram-v2
`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.

Loading