Rasmus Munk LarsenandRasmus Munk Larsen
27cce38d14
libeigen/eigen!2559 Co-authored-by: Rasmus Munk Larsen <rmlarsen@gmail.com>
272 lines
10 KiB
Markdown
272 lines
10 KiB
Markdown
# Releasing Eigen
|
|
|
|
Checklist for cutting an Eigen release (major / minor / patch) from the
|
|
upstream repository at <https://gitlab.com/libeigen/eigen>.
|
|
|
|
The mechanical steps below are the *what*. The decisions around them
|
|
(timing, scope, what counts as a breaking change) are a maintainer call
|
|
and intentionally not encoded here.
|
|
|
|
## Versioning
|
|
|
|
Eigen follows [Semantic Versioning 2.0.0](https://semver.org/) as of
|
|
5.0 — see the transition table in [`CHANGELOG.md`](CHANGELOG.md) under
|
|
the 5.0.0 entry. Versions are `MAJOR.MINOR.PATCH`:
|
|
|
|
- Bump `MAJOR` for backward-incompatible API or ABI changes.
|
|
- Bump `MINOR` for backward-compatible feature additions.
|
|
- Bump `PATCH` for backward-compatible bug fixes only.
|
|
|
|
The legacy `WORLD` field is frozen at `3` for posterity and plays no
|
|
role in release decisions; `Eigen/Version` keeps the `#define
|
|
EIGEN_WORLD_VERSION 3` line, but only `MAJOR`/`MINOR`/`PATCH` move.
|
|
|
|
## Scope
|
|
|
|
Two flows are described:
|
|
|
|
- **Major / minor release** (`X.Y.0`) — cuts a new `X.Y` release branch
|
|
from `master`, ships the accumulated `[Unreleased]` work. Tag `5.0.0`
|
|
is the most recent example.
|
|
- **Patch release** (`X.Y.Z`, `Z ≥ 1`) — adds cherry-picked fixes to an
|
|
existing `X.Y` release branch. Tag `5.0.1` is the most recent example.
|
|
|
|
Choosing between them is a judgment call (SemVer is the rule, but
|
|
"large enough" varies). See work item
|
|
[#3051](https://gitlab.com/libeigen/eigen/-/work_items/3051) for a
|
|
recent case where a proposed 5.0.2 patch was reconsidered as a minor
|
|
release once maintainers reviewed scope. Resolve this on the mailing
|
|
list / Discord before any branch or version work.
|
|
|
|
## Prerequisites
|
|
|
|
- Push rights to `upstream` (`https://gitlab.com/libeigen/eigen.git`).
|
|
- A GitLab personal access token with `api` scope, exported as
|
|
`GITLAB_PRIVATE_TOKEN`. All `scripts/gitlab_api_*.py` helpers fall
|
|
back to this environment variable.
|
|
- A clean working tree on `master` (for a major / minor cut) or on the
|
|
release branch (for a patch).
|
|
|
|
## Version source of truth
|
|
|
|
Everything reads from [`Eigen/Version`](Eigen/Version). `Macros.h` does
|
|
not hard-code version numbers; `CMakeLists.txt` parses the
|
|
`#define` lines from `Eigen/Version` at configure time. Editing
|
|
`Eigen/Version` is the single version bump.
|
|
|
|
Field conventions observed in history:
|
|
|
|
| State | `PATCH` | `PRERELEASE` | `BUILD` | `VERSION_STRING` |
|
|
| -------------------------------------- | ------- | ------------ | --------- | ----------------------- |
|
|
| At the release tag | `Z` | `""` | `""` | `"X.Y.Z"` |
|
|
| Release branch after the tag (dev) | `Z+1` | `"dev"` | `"X.Y"` | `"X.Y.(Z+1)-dev+X.Y"` |
|
|
| `master` between releases (dev) | `Z` | `"dev"` | `"master"`| `"X.Y.Z-dev+master"` |
|
|
|
|
Reference commits:
|
|
|
|
- `151b95d07` — `bump to 5.0.0` (set the released form).
|
|
- `0db477863` — `Set 5.0.1 release version` (same pattern, for a patch).
|
|
- `4abf3bd54` / `ccde35bcd` — post-release dev bump on the release
|
|
branch and on `master` respectively.
|
|
|
|
## 1. Pre-release (shared)
|
|
|
|
Gather the changelog material and label the included MRs / issues so
|
|
the `release::X.Y.Z` query links in `CHANGELOG.md` resolve.
|
|
|
|
```sh
|
|
export GITLAB_PRIVATE_TOKEN=...
|
|
|
|
# 1. Dump everything that closed / was merged since the last release
|
|
# (parallel). The scripts filter by `updated_at` (closest available
|
|
# proxy for merge/close time), which can over-include — the human
|
|
# narrows down in step 3.
|
|
python3 scripts/gitlab_api_mrs.py \
|
|
--state merged \
|
|
--updated_after YYYY-MM-DD \
|
|
--updated_before YYYY-MM-DD \
|
|
--related_issues --closes_issues > mrs.json &
|
|
python3 scripts/gitlab_api_issues.py \
|
|
--state closed \
|
|
--updated_after YYYY-MM-DD \
|
|
--updated_before YYYY-MM-DD > issues.json &
|
|
wait
|
|
|
|
# 2. Map commits to their MRs / issues.
|
|
git log --pretty=%H <prev-tag>..<head> > commits.txt
|
|
python3 scripts/git_commit_mrs_and_issues.py \
|
|
--merge_requests_file mrs.json \
|
|
--commits commits.txt > commit_map.json
|
|
|
|
# 3. Decide the final included set and write it to filtered files
|
|
# (selected_mrs.json / selected_issues.json) — typically by walking
|
|
# `commit_map.json` and dropping anything out of scope. Then label
|
|
# only that set; the CHANGELOG label-query links in sections 2c / 3c
|
|
# depend on these labels.
|
|
python3 scripts/gitlab_api_labeller.py release::X.Y.Z \
|
|
--mrs $(jq -r '.[].iid' selected_mrs.json) \
|
|
--issues $(jq -r '.[].iid' selected_issues.json)
|
|
```
|
|
|
|
## 2. Major / minor release (`X.Y.0`)
|
|
|
|
All steps are on the upstream repo. The release branch is just `X.Y`
|
|
(no `release/` prefix; matches existing `3.4`, `5.0`).
|
|
|
|
a. **Cut the release branch from `master`.**
|
|
|
|
```sh
|
|
git fetch upstream
|
|
git checkout -b X.Y upstream/master
|
|
git push upstream X.Y
|
|
```
|
|
|
|
b. **On the release branch, set the released form of `Eigen/Version`.**
|
|
|
|
```c
|
|
#define EIGEN_MAJOR_VERSION X
|
|
#define EIGEN_MINOR_VERSION Y
|
|
#define EIGEN_PATCH_VERSION 0
|
|
#define EIGEN_PRERELEASE_VERSION ""
|
|
#define EIGEN_BUILD_VERSION ""
|
|
#define EIGEN_VERSION_STRING "X.Y.0"
|
|
```
|
|
|
|
c. **Promote `[Unreleased]` in `CHANGELOG.md` to `## [X.Y.0] - YYYY-MM-DD`.**
|
|
Use the [5.0.0 entry](CHANGELOG.md) as the template — typical
|
|
sub-sections include `### Versioning`, `### Breaking changes`, then
|
|
per-area sections (`### Elementwise math functions`, `### Dense matrix
|
|
decompositions`, etc.). Include label-query links of the form
|
|
`https://gitlab.com/libeigen/eigen/-/issues?state=all&label_name%5B%5D=release%3A%3AX.Y.0`
|
|
and the analogous merge-requests query.
|
|
|
|
d. **Commit and tag.** Tags are lightweight (no `v` prefix).
|
|
|
|
```sh
|
|
git commit Eigen/Version CHANGELOG.md -m "Set X.Y.0 release version."
|
|
git tag X.Y.0
|
|
git push upstream X.Y X.Y.0
|
|
```
|
|
|
|
e. **Post-tag dev bump of the release branch.** Set `PATCH=1`,
|
|
`PRERELEASE="dev"`, `BUILD="X.Y"`,
|
|
`VERSION_STRING="X.Y.1-dev+X.Y"`. Commit subject:
|
|
`Update dev version number.`
|
|
|
|
f. **Post-tag bookkeeping on `master`.** There is no rigid convention
|
|
for how `master`'s `Eigen/Version` advances after a release — today
|
|
master tracks the next patch (`5.0.1-dev+master`); for a minor or
|
|
major release decide with maintainers whether to bump
|
|
`MAJOR`/`MINOR` on `master` as well.
|
|
|
|
## 3. Patch release (`X.Y.Z`, `Z ≥ 1`)
|
|
|
|
a. **Cherry-pick fixes from `master` to the `X.Y` release branch.**
|
|
|
|
```sh
|
|
git checkout X.Y
|
|
git pull upstream X.Y
|
|
git cherry-pick -x <sha> # -x records the source SHA
|
|
```
|
|
|
|
Use `cherry-pick -x` consistently — `git_commit_mrs_and_issues.py`
|
|
walks `(cherry picked from commit ...)` trailers to attribute work
|
|
back to its original MR. Re-run CI on the branch after each pick (or
|
|
after each batch) so a bad pick can be reverted in isolation.
|
|
|
|
Driving this by hand is tedious. Steve Bronder's
|
|
[`apply_patches.py`](https://gist.github.com/SteveBronder/474845f6673100e9928872a407244362)
|
|
(linked from
|
|
[#3051](https://gitlab.com/libeigen/eigen/-/work_items/3051)) is
|
|
prior art: it reads a CSV of SHAs, cherry-picks each onto a fresh
|
|
branch, and runs configure / build / tests after each pick. The repo
|
|
does not yet vendor an equivalent; if you write one, put it under
|
|
`scripts/`.
|
|
|
|
b. **On the release branch, set the released form of `Eigen/Version`.**
|
|
Bump `PATCH` to `Z`, clear `PRERELEASE` and `BUILD`, update
|
|
`VERSION_STRING` to `"X.Y.Z"` (model: `0db477863`).
|
|
|
|
c. **Add a `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md`.**
|
|
The [5.0.1 entry](CHANGELOG.md) is the template: a short intro plus
|
|
a bulleted list of fixes with `[#nnnn]` / `[!nnnn]` references, then
|
|
the two `release::X.Y.Z` label-query links.
|
|
|
|
d. **Commit and tag.**
|
|
|
|
```sh
|
|
git commit Eigen/Version CHANGELOG.md -m "Set X.Y.Z release version."
|
|
git tag X.Y.Z
|
|
git push upstream X.Y X.Y.Z
|
|
```
|
|
|
|
e. **Post-tag dev bump of the release branch.** Set `PATCH=Z+1`,
|
|
`PRERELEASE="dev"`, `BUILD="X.Y"`,
|
|
`VERSION_STRING="X.Y.(Z+1)-dev+X.Y"`. Commit subject:
|
|
`Update dev version number.`
|
|
|
|
## 4. Publish archives to the GitLab package registry
|
|
|
|
After the tag is pushed, mirror GitLab's auto-generated tag archives
|
|
into the project's generic package registry with SHA-256 checksums:
|
|
|
|
```sh
|
|
python3 scripts/gitlab_api_deploy_package.py --version X.Y.Z
|
|
```
|
|
|
|
The script downloads `eigen-X.Y.Z.{tar.gz,tar.bz2,tar,zip}` from
|
|
`https://gitlab.com/libeigen/eigen/-/archive/X.Y.Z/`, computes
|
|
SHA-256 sums, and uploads each archive + its `.sha256` companion to
|
|
`projects/15462818/packages/generic/eigen/X.Y.Z/`.
|
|
|
|
## 5. Create the GitLab Release object
|
|
|
|
Manual step in the GitLab UI (no CI automation today): **Project →
|
|
Deploy → Releases → New release**. Pick the tag, write a short
|
|
description (link to the matching `CHANGELOG.md` section), and add
|
|
the package-registry archive URLs from step 4 as release assets.
|
|
|
|
## 6. Documentation
|
|
|
|
Per-branch Doxygen output lands on GitLab Pages under
|
|
`https://libeigen.gitlab.io/eigen/docs-<branch>` via the `deploy:docs`
|
|
job in [`ci/deploy.gitlab-ci.yml`](ci/deploy.gitlab-ci.yml). The job
|
|
fires on schedule, on web-triggered pipelines, and on push to the
|
|
default branch, only inside the `libeigen` namespace.
|
|
|
|
To publish docs for a release branch / tag, trigger a **Web** pipeline
|
|
on the release branch from **Build → Pipelines → Run pipeline**. The
|
|
`PAGES_PREFIX` becomes `docs-<branch>` and the URL becomes
|
|
`https://libeigen.gitlab.io/eigen/docs-<branch>`.
|
|
|
|
Manual build fallback (developer machine, when CI Pages isn't an
|
|
option):
|
|
|
|
```sh
|
|
mkdir -p build && cd build
|
|
cmake .. && make doc
|
|
# output: build/doc/html/
|
|
```
|
|
|
|
The `scripts/eigen_gen_docs` shell script is obsolete (it rsyncs to
|
|
`ssh.tuxfamily.org`, the pre-GitLab docs host). Do not use it.
|
|
|
|
## 7. Announcements
|
|
|
|
All manual; no tooling in-repo.
|
|
|
|
- Eigen mailing list.
|
|
- Discord `#announcements`.
|
|
- Project website news / wiki page (verify still maintained before
|
|
posting).
|
|
- Downstream packagers as best-effort: Homebrew, major Linux distros,
|
|
Compiler Explorer (godbolt).
|
|
|
|
## 8. Cleanup
|
|
|
|
- Open the `release::X.Y.Z` issue and MR query links from the new
|
|
`CHANGELOG.md` entry and confirm they return non-empty results.
|
|
- Close the GitLab milestone for this release if one was used.
|
|
- On `master`, ensure `CHANGELOG.md`'s `[Unreleased]` section is empty
|
|
(or re-create it) so the next release's notes start clean.
|