Repository navigation
ci(release): add CalVer release guards and cut-sdk-release workflow - #106
Conversation
8fc520e to
0c5a6a4
Compare
damaz91
left a comment
There was a problem hiding this comment.
Thanks for putting this together! Action SHA pins, zizmor hygiene, PyPI OIDC environment scoping, setup-uv cache handling on tag runs, and ucp-automation App token usage for cascading release: [published] triggers all look great.
Left inline comments on a few items to address before cutting releases:
- Sequencing prerequisite (
feat/ucp-lock-and-draft-channel) & rebase:ucp-lock.json, the newgenerate_models.shlock flags, and dynamicimportlib.metadata.version("ucp-sdk")insrc/ucp_sdk/__init__.pyaren't onmainyet (and rebasing ontomainafter#103will clear themodel-driftcheck). - Upstream
ucp_shaancestry check inrelease.yml: Verifyucp-lock.json'sucp_shais actually an ancestor oforigin/release/YYYY-MM-DDinUniversal-Commerce-Protocol/ucpbefore publishing. - GitHub "Latest" Release badge on maintenance cuts: Pass
--latest=falsetogh release createwhen cutting a patch/minor release for an older spec epoch (plus--verify-tag). publish_release: falsefollow-up path: Allow publishing an already-prepared untagged release branch version without skipping.0.0.
(Note for repo admin setup: python-sdk currently only scopes PR Config rulesets to main; if release/** branch protection rulesets are added later to match ucp, ucp-automation will need bypass permissions so cut-sdk-release.yml can push directly to refs/heads/release/YYYY-MM-DD.)
| if [ "$BUMP_MODE" = "initial" ]; then | ||
| if git show-ref --verify --quiet "refs/remotes/origin/${RELEASE_BRANCH}"; then | ||
| echo "::error::Branch ${RELEASE_BRANCH} already exists; use bump=patch or bump=minor" | ||
| exit 1 | ||
| fi | ||
| git checkout -B "$RELEASE_BRANCH" origin/main | ||
| NEW_VERSION="${EPOCH}.0.0" | ||
| else | ||
| if ! git show-ref --verify --quiet "refs/remotes/origin/${RELEASE_BRANCH}"; then | ||
| echo "::error::Branch ${RELEASE_BRANCH} does not exist; use bump=initial first" | ||
| exit 1 | ||
| fi | ||
| git checkout -B "$RELEASE_BRANCH" "origin/${RELEASE_BRANCH}" | ||
| CURRENT_VERSION="$(python3 - <<'PY' | ||
| from pathlib import Path | ||
| import sys | ||
| import tomllib | ||
|
|
||
| data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8")) | ||
| version = data.get("project", {}).get("version") | ||
| if not isinstance(version, str) or not version: | ||
| sys.exit(1) | ||
| print(version) | ||
| PY | ||
| )" | ||
| if [[ ! "$CURRENT_VERSION" =~ ^${EPOCH}\.([0-9]+)\.([0-9]+)$ ]]; then | ||
| echo "::error::Current pyproject.toml version '$CURRENT_VERSION' does not match ${EPOCH}.MINOR.PATCH" | ||
| exit 1 | ||
| fi | ||
| MINOR="${BASH_REMATCH[1]}" | ||
| PATCH="${BASH_REMATCH[2]}" | ||
| if [ "$BUMP_MODE" = "patch" ]; then | ||
| NEW_VERSION="${EPOCH}.${MINOR}.$((PATCH + 1))" | ||
| else | ||
| NEW_VERSION="${EPOCH}.$((MINOR + 1)).0" | ||
| fi | ||
| fi |
There was a problem hiding this comment.
When dispatched with publish_release: false, this workflow still commits and pushes NEW_VERSION (${EPOCH}.0.0 or the bumped patch/minor version) to origin/${RELEASE_BRANCH} without creating the tag/release. There is currently no way to subsequently publish that prepared version via cut-sdk-release.yml: re-running bump=initial fails at L116–119 because ${RELEASE_BRANCH} already exists, while running bump=patch increments to .0.1 (L147) and permanently skips .0.0.
Consider adding a publish-existing / none option (or allowing bump=initial when origin/${RELEASE_BRANCH} is at ${EPOCH}.0.0 and refs/tags/v${EPOCH}.0.0 does not exist yet), and failing loudly at L280 if git diff --cached --quiet is unexpectedly empty during a version bump.
There was a problem hiding this comment.
Good catch, updated in 79a8c53. Added a publish-existing option to bump that verifies the prepared commit and lockfile on the release branch and tags/publishes it without bumping past .0.0, and made initial/patch/minor bumps fail loudly if the staged diff is empty.
| NEW_VERSION: ${{ steps.prep.outputs.new_version }} | ||
| run: | | ||
| set -euo pipefail | ||
| ./generate_models.sh "$RUNNER_TEMP/ucp-spec" --channel release --ref "$RELEASE_BRANCH" --write-lock |
There was a problem hiding this comment.
Sequencing note: ucp-lock.json, the --channel / --ref / --write-lock / --from-lock flags in generate_models.sh, and dynamic importlib.metadata.version("ucp-sdk") in src/ucp_sdk/__init__.py are not on main yet (currently on feat/ucp-lock-and-draft-channel, while main still hardcodes __version__ = "0.6.0" and ignores flags past $1). That prerequisite PR will need to merge before running this workflow, and rebasing #106 onto main after #103 will clear the failing Generated models match the pinned UCP spec CI job.
There was a problem hiding this comment.
| gh release create "v${NEW_VERSION}" \ | ||
| --repo "$REPOSITORY" \ | ||
| --target "$RELEASE_BRANCH" \ | ||
| --title "v${NEW_VERSION}" \ | ||
| --generate-notes | ||
| fi |
There was a problem hiding this comment.
Two small release-creation edge cases here:
- GitHub "Latest" badge regression on older epochs: Omitting
--latestleaves GitHub's REST APImake_latestat its default ("true"), so cutting a maintenance patch on an older spec branch (e.g.v20260825.0.1afterv20261208.0.0is live) will move the repository's Latest release badge (/releases/latest) backward. Consider checking the current latest GitHub Release tag epoch and passing--latest=falsewhenever10#$EPOCH < 10#$LATEST_EPOCH. - Bind to pushed tag: Since the annotated tag
v${NEW_VERSION}was pushed on L287, prefer--verify-taginstead of--target "$RELEASE_BRANCH"so the release attaches directly to the pushed tag object rather than a mutable branch ref.
There was a problem hiding this comment.
Updated in 79a8c53. Release creation now passes --verify-tag instead of --target and compares the release epoch against published CalVer releases so --latest=false is passed whenever cutting a maintenance release on an older spec branch.
| RELEASE_TAG: ${{ github.ref_name }} | ||
| run: | | ||
| set -euo pipefail | ||
| if [[ ! "$RELEASE_TAG" =~ ^v([0-9]{4})([0-9]{2})([0-9]{2})\.([0-9]+)\.([0-9]+)$ ]]; then |
There was a problem hiding this comment.
Consider tightening MINOR and PATCH to (0|[1-9][0-9]*) and validating datetime.date(int(yyyy), int(mm), int(dd)) (here and in cut-sdk-release.yml L69 / L140) so invalid calendar dates and non-canonical leading-zero segments like v20260825.01.0 (which hatchling normalizes to 20260825.1.0 in built wheel metadata) are rejected upfront.
There was a problem hiding this comment.
Updated in 79a8c53. Tightened minor and patch segments to (0|[1-9][0-9]*) and added date -u -d calendar date validation across both release.yml and cut-sdk-release.yml.
| ucp_sha = lock.get("ucp_sha", "") | ||
| if not re.fullmatch(r"[0-9a-f]{40}", str(ucp_sha)): | ||
| print( | ||
| f"::error::ucp-lock.json ucp_sha must be a 40-char lowercase hex SHA, got {ucp_sha!r}", | ||
| file=sys.stderr, | ||
| ) | ||
| sys.exit(1) | ||
| schema_version = str(lock.get("ucp_schema_version", "")).strip() |
There was a problem hiding this comment.
verify checks channel == "release", ucp_ref == expected_branch, and the 40-char hex format of ucp_sha, and L155 runs ./generate_models.sh --from-lock (which clones ucp and checks out LOCK_SHA detached). If ucp-lock.json has ucp_sha pointing to an unreleased draft commit on ucp main while channel/ucp_ref say release, all checks pass and draft schemas get published under a stable CalVer release.
Consider cloning ucp once into $RUNNER_TEMP/ucp-spec, asserting git -C "$RUNNER_TEMP/ucp-spec" merge-base --is-ancestor "$UCP_SHA" "origin/${EXPECTED_BRANCH}" (matching cut-sdk-release.yml L97), and passing --spec-dir "$RUNNER_TEMP/ucp-spec" to ./generate_models.sh --from-lock on L155 to close that gap without an extra clone.
There was a problem hiding this comment.
Great catch, updated in 79a8c53. verify now clones ucp once into $RUNNER_TEMP/ucp-spec, asserts that ucp_sha is an ancestor of origin/release/YYYY-MM-DD, and reuses that checkout via --spec-dir during model drift verification.
| set -euo pipefail | ||
| uv run python -m unittest discover -s tests -p "test_*.py" | ||
| ./generate_models.sh --from-lock | ||
| git diff --exit-code |
There was a problem hiding this comment.
git diff --exit-code ignores untracked files under src/ucp_sdk/models/schemas/, whereas hatchling packages everything under src/ucp_sdk/. Checking [ -z "$(git status --porcelain -- src/ucp_sdk pyproject.toml ucp-lock.json)" ] (matching tests.yml) ensures untracked generated files fail the drift gate too.
There was a problem hiding this comment.
Updated in 79a8c53 to check git status --porcelain -- src/ucp_sdk pyproject.toml ucp-lock.json so untracked files under src/ucp_sdk also fail the drift gate.
40bab0c to
aec7f4a
Compare
aec7f4a to
79a8c53
Compare
79a8c53 to
2d49d7c
Compare
damaz91
left a comment
There was a problem hiding this comment.
Thanks for addressing all the review feedback and rebasing onto main after #109!
The publish-existing flow, empty-diff guard, upstream ucp release-branch ancestry check, --verify-tag + --latest=false epoch handling, canonical CalVer/calendar date validation, and untracked-aware drift checks all look solid.
(Two tiny non-blocking follow-ups if touching cut-sdk-release.yml later: setup-uv enable-cache: true with read-only GITHUB_TOKEN logs a harmless cache-reservation warning in its post step—matching enable-cache: false in release.yml/tests.yml avoids it; and in publish-existing mode with blank ucp_sha, defaulting RESOLVED_UCP_SHA from ucp-lock.json would avoid failing closed if upstream ucp release/<spec_version> advanced after a dry-run cut.)
Summary
Hardens the PyPI publishing workflow with pre-publish release guards and adds a manual dispatch workflow for cutting and tagging forward-only CalVer SDK releases (
YYYYMMDD.MINOR.PATCH,ucp#909).release.yml) with serializedpypi-release-publishconcurrency, full git history, canonicalvYYYYMMDD.MINOR.PATCH(YYYYMMDD >= 20260825) and real calendar date validation,pyproject.tomlanducp-lock.jsonprovenance checks, SDK and upstreamucprelease-branch ancestry assertions, unit tests, and untracked-awaregit status --porcelainmodel drift verification before building and publishing.cut-sdk-release.yml(workflow_dispatch) to create or updaterelease/YYYY-MM-DDbranches, regenerate models anducp-lock.jsonagainst the UCP release branch, bumpYYYYMMDD.MINOR.PATCH(initial,patch,minor, orpublish-existingfor untagged prepared release commits), run unit tests and package build checks, and publish tagged GitHub Releases (--verify-tag, with--latest=falseon older-epoch maintenance cuts) using theucp-automationGitHub App token sorelease.ymltriggers automatically.