fix release script

Author: fswair

Makefile

@@ -113,7 +113,7 @@ release-check:
 
 release-artifacts:
 	@if [ -z "$(RELEASE_TAG)" ]; then \
-		echo "Error: RELEASE_TAG is required. Usage: make release RELEASE_TAG=v1.0.0"; \
+		echo "Error: RELEASE_TAG is required. Usage: make release RELEASE_TAG=v1.0.0_2026-07-04"; \
 		exit 1; \
 	fi
 	@printf "$(BLUE)==>$(RESET) Building and smoke testing release artifacts...\n"

docs/release-process.md

@@ -16,7 +16,7 @@ only when every package reports the same PEP 440 version.
 Run the complete release gate:
 
 ```bash
-make release RELEASE_TAG=v1.0.0
+make release RELEASE_TAG=v1.0.0_2026-07-04
 ```
 
 The gate:
@@ -32,13 +32,17 @@ The gate:
 
 ## Publish
 
-Push the exact matching tag:
+Push a matching version tag. An optional ISO date suffix can distinguish the
+repository release event without changing the package version:
 
 ```bash
-git tag -s v1.0.0 -m "ACP Kit 1.0.0"
-git push origin v1.0.0
+git tag -s v1.0.0_2026-07-04 -m "ACP Kit 1.0.0"
+git push origin v1.0.0_2026-07-04
 ```
 
+Both `v1.0.0` and `v1.0.0_YYYY-MM-DD` validate against package version
+`1.0.0`. The suffix does not permit republishing an existing PyPI version.
+
 GitHub Actions repeats the release gate, uploads the artifacts for inspection,
 and publishes through PyPI Trusted Publishing. Never publish from a dirty
 worktree or bypass a failed artifact smoke test.

scripts/release.py

@@ -10,6 +10,7 @@
 import tomllib
 import zipfile
 from dataclasses import dataclass
+from datetime import date
 from email.message import Message
 from email.parser import Parser
 from pathlib import Path
@@ -23,6 +24,7 @@
     r"^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)"
     r"(?:(?:a|b|rc)\d+)?$"
 )
+_RELEASE_DATE_PATTERN: Final[re.Pattern[str]] = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 
 
 class ReleaseValidationError(RuntimeError):
@@ -128,14 +130,34 @@ def _check_root_extras(root: Path, version: str) -> None:
             )
 
 
+def _check_release_tag(tag: str, version: str) -> None:
+    version_tag = f"v{version}"
+    if tag == version_tag:
+        return
+
+    dated_prefix = f"{version_tag}_"
+    if tag.startswith(dated_prefix):
+        release_date = tag.removeprefix(dated_prefix)
+        if _RELEASE_DATE_PATTERN.fullmatch(release_date) is not None:
+            try:
+                date.fromisoformat(release_date)
+            except ValueError:
+                pass
+            else:
+                return
+
+    raise ReleaseValidationError(
+        f"Release tag {tag!r} does not match workspace version {version!r}; "
+        f"expected {version_tag!r} or {version_tag + '_YYYY-MM-DD'!r}."
+    )
+
+
 def check_release(*, root: Path, tag: str | None) -> str:
     version = _workspace_version(root)
     _check_changelog(root, version)
     _check_root_extras(root, version)
-    if tag is not None and tag != f"v{version}":
-        raise ReleaseValidationError(
-            f"Release tag {tag!r} does not match workspace version {version!r}."
-        )
+    if tag is not None:
+        _check_release_tag(tag, version)
     print(f"Release metadata valid for {version}.")
     return version
 
@@ -334,7 +356,10 @@ def _parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     check_parser = subparsers.add_parser("check", help="Validate release metadata.")
-    check_parser.add_argument("--tag", help="Expected git tag, for example v1.0.0.")
+    check_parser.add_argument(
+        "--tag",
+        help="Expected git tag, for example v1.0.0 or v1.0.0_2026-07-04.",
+    )
 
     build_parser = subparsers.add_parser("build", help="Build and validate all artifacts.")
     build_parser.add_argument("--output-dir", type=Path, default=Path("dist"))
@@ -347,7 +372,11 @@ def _parser() -> argparse.ArgumentParser:
     prepare_parser = subparsers.add_parser(
         "prepare", help="Validate, build, and smoke test a tagged release."
     )
-    prepare_parser.add_argument("--tag", required=True)
+    prepare_parser.add_argument(
+        "--tag",
+        required=True,
+        help="Git tag, for example v1.0.0 or v1.0.0_2026-07-04.",
+    )
     prepare_parser.add_argument("--output-dir", type=Path, default=Path("dist"))
     return parser
 

tests/test_release.py

@@ -27,8 +27,22 @@ def test_release_metadata_matches_current_version_and_tag() -> None:
     assert f"Release metadata valid for {acpkit.__version__}." in result.stdout
 
 
+def test_release_metadata_accepts_dated_tag() -> None:
+    result = _run_release("check", "--tag", f"v{acpkit.__version__}_2026-07-04")
+
+    assert result.returncode == 0
+    assert f"Release metadata valid for {acpkit.__version__}." in result.stdout
+
+
 def test_release_metadata_rejects_mismatched_tag() -> None:
     result = _run_release("check", "--tag", "v999.0.0")
 
     assert result.returncode == 1
     assert "does not match workspace version" in result.stderr
+
+
+def test_release_metadata_rejects_invalid_release_date() -> None:
+    result = _run_release("check", "--tag", f"v{acpkit.__version__}_2026-02-30")
+
+    assert result.returncode == 1
+    assert "does not match workspace version" in result.stderr