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.
Eigen follows Semantic Versioning 2.0.0 as of 5.0 — see the transition table in CHANGELOG.md under the 5.0.0 entry. Versions are MAJOR.MINOR.PATCH:
MAJOR for backward-incompatible API or ABI changes.MINOR for backward-compatible feature additions.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.
Two flows are described:
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.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 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.
upstream (https://gitlab.com/libeigen/eigen.git).api scope, exported as GITLAB_PRIVATE_TOKEN. All scripts/gitlab_api_*.py helpers fall back to this environment variable.master (for a major / minor cut) or on the release branch (for a patch).Everything reads from 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.Gather the changelog material and label the included MRs / issues so the release::X.Y.Z query links in CHANGELOG.md resolve.
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)
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.
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.
#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 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).
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.
X.Y.Z, Z ≥ 1)a. Cherry-pick fixes from master to the X.Y release branch.
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 (linked from #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 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.
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.
After the tag is pushed, mirror GitLab‘s auto-generated tag archives into the project’s generic package registry with SHA-256 checksums:
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/.
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.
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. 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):
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.
All manual; no tooling in-repo.
#announcements.release::X.Y.Z issue and MR query links from the new CHANGELOG.md entry and confirm they return non-empty results.master, ensure CHANGELOG.md‘s [Unreleased] section is empty (or re-create it) so the next release’s notes start clean.