feat: support post-release preparation

Signed-off-by: Aaron Gonzales <aagonzales@nvidia.com>

Author: binaryaaron

.github/workflows/container-build.yml

@@ -85,8 +85,8 @@ jobs:
             type=raw,value=${{ matrix.variant }},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
             type=raw,value=latest-${{ matrix.variant }},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
             type=sha,prefix=sha-,suffix=-${{ matrix.variant }}
-            type=semver,pattern={{version}}-${{ matrix.variant }}
-            type=semver,pattern={{major}}.{{minor}}-${{ matrix.variant }}
+            type=pep440,pattern={{version}}-${{ matrix.variant }}
+            type=pep440,pattern={{major}}.{{minor}}-${{ matrix.variant }}
           labels: |
             org.opencontainers.image.version=${{ steps.package-version.outputs.version }}
             com.nvidia.nemo.safe-synthesizer.extra=${{ matrix.extra }}

.mise/tasks/release/prepare

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
-#MISE description="Prepare the next rc0 release tag from local Git tags without creating, deleting, or pushing tags."
+#MISE description="Prepare the next release tag from local Git tags without creating, deleting, or pushing tags."
 
 set -euo pipefail
 source "${MISE_CONFIG_ROOT}/.mise/tasks/_lib.sh"

CONTRIBUTING.md

@@ -685,14 +685,14 @@ Before contributing, run `mise run format` and `mise run check`. See `AGENTS.md`
 
 Pushing a `v*` tag starts two workflows. [`release.yml`](.github/workflows/release.yml)
 publishes the wheel to Test PyPI and PyPI, creates a GitHub release, and
-publishes versioned documentation for stable releases.
+publishes versioned documentation for final releases, including post-releases.
 [`container-build.yml`](.github/workflows/container-build.yml) publishes the
 CUDA image to GitHub Container Registry (GHCR).
 
 Release versions follow [PEP 440](https://peps.python.org/pep-0440/) with major,
-minor, and patch release numbers. This project uses stable releases and release
-candidates only; prerelease versions append `rcN` without a dash. The GitHub tag
-always starts with a `v` prefix.
+minor, and patch release numbers. This project uses stable releases, release
+candidates, and post-releases. Prerelease versions append `rcN` without a dash;
+post-releases append `.postN`. The GitHub tag always starts with a `v` prefix.
 
 Examples:
 
@@ -702,9 +702,11 @@ Examples:
 | `v2.1.3`      | `2.1.3`      | ✅                                              |
 | `v0.0.5rc0`   | `0.0.5rc0`   | ✅                                              |
 | `v0.1.2rc5`   | `0.1.2rc5`   | ✅                                              |
+| `v0.1.6.post1` | `0.1.6.post1` | ✅                                              |
 | `1.0.0`       |              | ❌ No `v` prefix                                |
 | `release-1.0` |              | ❌ Wrong format                                 |
 | `v0.0.7-rc4`  |              | ❌ Dash before rc suffix                        |
+| `v0.1.6-post1` |               | ❌ Dash before post-release suffix              |
 | `v0.1.3a1`    |              | ❌ Alpha prereleases are not used; use rcN only |
 
 ### Release Checklist
@@ -713,8 +715,8 @@ Examples:
 
 - Fetch `origin/main` and tags, choose the exact release commit, and confirm its
   normal CI and manually dispatched GPU Tests run passed.
-- Choose unused candidate and stable tags, then record the candidate's exact
-  `origin/main` SHA.
+- Choose the unused tag or tags required for the release type, then record the
+  exact `origin/main` SHA.
 - Decide whether GHCR visibility or a separate nSpect or Pulse scan blocks the
   release. Those scans are not part of the GitHub release workflows.
 
@@ -785,21 +787,48 @@ git tag "${STABLE_TAG}" "${RELEASE_SHA}"
 git push origin "refs/tags/${STABLE_TAG}"
 ```
 
-#### After Publishing Stable
+#### Post-release
+
+Use a post-release for a packaging or release correction that does not warrant
+a new regular patch version. A post-release is final, so it does not use the
+release-candidate promotion sequence. Preview the next post-release tag and
+resolve its target commit without creating or pushing a tag:
+
+```bash
+mise run release:prepare -- --bump post --ref origin/main
+```
+
+After reviewing the output, create the proposed tag at the resolved commit and
+push it. For example:
+
+```bash
+POST_TAG=v0.1.6.post1
+RELEASE_SHA="$(git rev-parse 'origin/main^{commit}')"
+git tag "${POST_TAG}" "${RELEASE_SHA}"
+git push origin "refs/tags/${POST_TAG}"
+```
+
+The container workflow publishes `X.Y.Z.postN-cu129`, the immutable
+`sha-<short-sha>-cu129` tag, and the mutable `cu129` and `latest-cu129` aliases.
+PEP 440 post-releases do not move the shortened `X.Y-cu129` tag. Validate the
+post-release wheel and immutable container tag before announcing the release.
+
+#### After Publishing a Final Release
 
 After publishing:
 
 - Verify both tag-triggered workflows passed at the tested SHA.
-- Confirm Test PyPI and production PyPI contain the stable version.
+- Confirm Test PyPI and production PyPI contain the published version.
 - Confirm the GitHub release is not marked as a prerelease.
 - Confirm versioned documentation is available at
   `https://nvidia-nemo.github.io/Safe-Synthesizer/<version>/`.
-- Confirm GHCR exposes the stable `X.Y.Z-cu129` and `X.Y-cu129` tags with the
-  intended visibility.
+- Confirm GHCR exposes the expected tags with the intended visibility. Regular
+  stable releases publish `X.Y.Z-cu129` and `X.Y-cu129`; post-releases publish
+  `X.Y.Z.postN-cu129` without moving `X.Y-cu129`.
 - Coordinate a NeMo Platform package or container pin, documentation update,
   and downstream release when Platform should consume the new version. This is
   not currently automated by the Safe Synthesizer release workflow.
-- Announce the release only after artifacts and stable documentation pass
+- Announce the release only after artifacts and versioned documentation pass
   verification.
 
 ## NMP Integration

tests/tools/test_release_version.py

@@ -85,6 +85,38 @@ def test_major_minor_and_patch_bumps_prepare_rc0(self) -> None:
                 plan = release_version.plan_release(bump=bump, cwd=self.repo)
                 self.assertEqual((plan.next_tag, plan.next_version), expected)
 
+    def test_post_bump_prepares_first_post_release(self) -> None:
+        self._tag("v1.5.0")
+        self._tag("v1.6.0")
+
+        plan = release_version.plan_release(bump="post", cwd=self.repo)
+
+        self.assertEqual(plan.latest_stable_tag, "v1.6.0")
+        self.assertEqual(plan.latest_stable_version, "1.6.0")
+        self.assertEqual(plan.bump, "post")
+        self.assertEqual(plan.next_tag, "v1.6.0.post1")
+        self.assertEqual(plan.next_version, "1.6.0.post1")
+
+    def test_post_bump_increments_highest_post_for_latest_stable(self) -> None:
+        self._tag("v1.5.0")
+        self._tag("v1.5.0.post7")
+        self._tag("v1.6.0")
+        self._tag("v1.6.0.post1")
+        self._tag("v1.6.0.post10")
+
+        plan = release_version.plan_release(bump="post", cwd=self.repo)
+
+        self.assertEqual(plan.next_tag, "v1.6.0.post11")
+
+    def test_regular_patch_accepts_post_tags_and_uses_stable_base(self) -> None:
+        self._tag("v1.6.0")
+        self._tag("v1.6.0.post1")
+
+        plan = release_version.plan_release(cwd=self.repo)
+
+        self.assertEqual(plan.latest_stable_tag, "v1.6.0")
+        self.assertEqual(plan.next_tag, "v1.6.1rc0")
+
     def test_json_cli_resolves_candidate_ref(self) -> None:
         self._tag("v0.1.0")
         first_commit = self._git("rev-parse", "HEAD")
@@ -110,6 +142,25 @@ def test_human_cli_does_not_create_candidate_tag(self) -> None:
         self.assertIn("No tag was created, deleted, or pushed.", result.stdout)
         self.assertEqual(self._git("tag", "--list"), tags_before)
 
+    def test_human_cli_describes_post_release_without_creating_tag(self) -> None:
+        self._tag("v1.6.0")
+        tags_before = self._git("tag", "--list")
+
+        result = self._run(sys.executable, str(TOOL_PATH), "--bump", "post")
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("Next Safe-Synthesizer post-release", result.stdout)
+        self.assertIn("Next post-release tag: v1.6.0.post1", result.stdout)
+        self.assertIn("No tag was created, deleted, or pushed.", result.stdout)
+        self.assertEqual(self._git("tag", "--list"), tags_before)
+
+    def test_post_release_without_matching_stable_tag_is_refused(self) -> None:
+        self._tag("v1.5.0")
+        self._tag("v1.6.0.post1")
+
+        with self.assertRaisesRegex(release_version.ReleaseVersionError, "missing stable tag v1.6.0"):
+            release_version.plan_release(bump="post", cwd=self.repo)
+
     def test_malformed_v_tag_is_an_explicit_error(self) -> None:
         self._tag("v0.1.0")
         self._tag("v0.2.0-rc0")

tests/tools/test_release_workflows.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from pathlib import Path
+
+import yaml
+
+WORKFLOW = Path(__file__).parents[2] / ".github" / "workflows" / "container-build.yml"
+
+
+def test_container_tags_use_pep440_versions() -> None:
+    workflow = yaml.load(WORKFLOW.read_text(), Loader=yaml.BaseLoader)
+    steps = workflow["jobs"]["build"]["steps"]
+    metadata_step = next(step for step in steps if step.get("name") == "Extract image metadata")
+    tags = metadata_step["with"]["tags"].splitlines()
+
+    assert "type=pep440,pattern={{version}}-${{ matrix.variant }}" in tags
+    assert "type=pep440,pattern={{major}}.{{minor}}-${{ matrix.variant }}" in tags
+    assert not any(tag.startswith("type=semver") for tag in tags)