RELEASING.md - mirror - Git at Google

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