Release

Release

Cuts a new version of the aegis-stack package itself (not a generated project). Bumps the version string, cuts the changelog, runs three independent gates, verifies an rc on TestPyPI, then tags for a real PyPI publish and verifies again against the published package.

When to use

Use when the task is "release a new version of aegis-stack" (bump the version, publish to PyPI, cut a GitHub release).

Do NOT use for ordinary feature or fix work with no release attached, and do NOT use for generated-project releases (those follow the target project's own process, not this one).

Files that change

Version bump (all five must be touched together; verify each file actually contains the version string before editing it, since it is easy to assume a file participates when it does not):

• aegis/__init__.py: __version__ = "X.Y.Z".
• pyproject.toml: version = "X.Y.Z" under [project].
• copier.yml (repo root): _version: "X.Y.Z".
• CHANGELOG.md: the version also appears here as the new dated section heading (see the changelog cut step in Procedure).
• uv.lock: the [[package]] name = "aegis-stack" entry's own version = "X.Y.Z" field. This one is not hand-edited; the pre-commit ty hook rewrites it, so stage it in a second commit pass (see Procedure).

Every other match of the old version string in the repo is test data or an unrelated coincidence; leave it alone.

Gate-relevant files (read, not edited, unless a gate fails):

• Makefile (repo root): check, test-stacks-full, test-stacks-quick targets.
• tests/test_runtime_dependencies.py: guards that ruff (and any other binary the updater shells out to at runtime) stays in [project].dependencies, not only a dev extra.
• .github/workflows/release.yml: the tag-triggered publish workflow (v*.*.*-rc* routes to TestPyPI, bare v*.*.* routes to PyPI); read this if tagging behavior is ever in question.

Procedure

1. Confirm the target version and the previous released tag.
2. Bump the version string in all five files listed above. Open each file and grep for the old version string to confirm the edit landed; do not assume a file needs changing just because a prior release touched it.
3. Cut the changelog in CHANGELOG.md: identify which items under [Unreleased] actually shipped in this release (cross-check with git log --first-parent <prev-tag>..HEAD so nothing merged after the branch point is mis-attributed), rename that content into a new dated [X.Y.Z] - YYYY-MM-DD section, draft the section body from the PR history for this range, and leave a fresh, empty ## [Unreleased] heading above it. This step is required and routinely forgotten; do not skip it.
4. Commit the version bump and changelog cut. If the pre-commit ty hook rewrites uv.lock during this commit, git add uv.lock and commit again so the lockfile's own version field matches.
5. Run the three gates (see Gates). Fix anything red before proceeding.
6. Tag the release commit as a release candidate: git tag vX.Y.Z-rcN && git push origin vX.Y.Z-rcN. This is what actually triggers the publish workflow; merging the version-bump PR alone publishes nothing.
7. Once the workflow is green, verify the rc via the TestPyPI upgrade-path recipe (see Gates, gate 3) run against the published rc rather than a local wheel.
8. If the rc verification finds a problem, fix it, bump to the next rc number (never reuse or re-tag a burned rc, see Pitfalls), and repeat from step 5.
9. Once an rc is clean, bump the version string from X.Y.ZrcN to the bare X.Y.Z in aegis/__init__.py, pyproject.toml, and copier.yml (the changelog section heading already says X.Y.Z from the cut; refresh uv.lock via uv lock), commit, and tag THAT commit: git tag vX.Y.Z && git push origin vX.Y.Z. Do not tag the rc commit itself: the publish workflow builds whatever version pyproject.toml carries, so tagging the rc commit as vX.Y.Z would publish an X.Y.ZrcN wheel under a final tag. This publishes to PyPI and drafts a GitHub release.
10. Post-publish, repeat the TestPyPI-style upgrade recipe once more against the now-published PyPI package (init the previous release, update to the new version) and grep the resulting project for conflict markers to confirm a clean upgrade path for real users.