Skip to content

ci(release): add CalVer release guards and cut-sdk-release workflow - #106

Merged
damaz91 merged 4 commits into
mainfrom
feat/calver-release-workflows
Nov 19, 2026
Merged

damaz91 merged 4 commits into
mainfrom
feat/calver-release-workflows

Conversation

@gsmith85

@gsmith85 gsmith85 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Updates the PyPI release workflow (release.yml) with serialized pypi-release-publish concurrency, full git history, canonical vYYYYMMDD.MINOR.PATCH (YYYYMMDD >= 20260825) and real calendar date validation, pyproject.toml and ucp-lock.json provenance checks, SDK and upstream ucp release-branch ancestry assertions, unit tests, and untracked-aware git status --porcelain model drift verification before building and publishing.
  • Adds cut-sdk-release.yml (workflow_dispatch) to create or update release/YYYY-MM-DD branches, regenerate models and ucp-lock.json against the UCP release branch, bump YYYYMMDD.MINOR.PATCH (initial, patch, minor, or publish-existing for untagged prepared release commits), run unit tests and package build checks, and publish tagged GitHub Releases (--verify-tag, with --latest=false on older-epoch maintenance cuts) using the ucp-automation GitHub App token so release.yml triggers automatically.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Nov 5, 2026
@gsmith85
gsmith85 force-pushed the feat/calver-release-workflows branch 2 times, most recently from 8fc520e to 0c5a6a4 Compare November 5, 2026 05:45
@damaz91 damaz91 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Nov 18, 2026

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Sequencing prerequisite (feat/ucp-lock-and-draft-channel) & rebase: ucp-lock.json, the new generate_models.sh lock flags, and dynamic importlib.metadata.version("ucp-sdk") in src/ucp_sdk/__init__.py aren't on main yet (and rebasing onto main after #103 will clear the model-drift check).
  2. Upstream ucp_sha ancestry check in release.yml: Verify ucp-lock.json's ucp_sha is actually an ancestor of origin/release/YYYY-MM-DD in Universal-Commerce-Protocol/ucp before publishing.
  3. GitHub "Latest" Release badge on maintenance cuts: Pass --latest=false to gh release create when cutting a patch/minor release for an older spec epoch (plus --verify-tag).
  4. publish_release: false follow-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.)

Comment on lines +115 to +151
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/cut-sdk-release.yml Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense! Opened #109 (79bbf75) for the lockfile, generate_models.sh shim (scripts/generate_models.py), and dynamic package version metadata (landing first before cutting releases), and rebased #106 onto main in 79a8c53 so the model-drift check is now green.

Comment thread .github/workflows/cut-sdk-release.yml Outdated
Comment on lines +288 to +293
gh release create "v${NEW_VERSION}" \
--repo "$REPOSITORY" \
--target "$RELEASE_BRANCH" \
--title "v${NEW_VERSION}" \
--generate-notes
fi

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two small release-creation edge cases here:

  1. GitHub "Latest" badge regression on older epochs: Omitting --latest leaves GitHub's REST API make_latest at its default ("true"), so cutting a maintenance patch on an older spec branch (e.g. v20260825.0.1 after v20261208.0.0 is live) will move the repository's Latest release badge (/releases/latest) backward. Consider checking the current latest GitHub Release tag epoch and passing --latest=false whenever 10#$EPOCH < 10#$LATEST_EPOCH.
  2. Bind to pushed tag: Since the annotated tag v${NEW_VERSION} was pushed on L287, prefer --verify-tag instead of --target "$RELEASE_BRANCH" so the release attaches directly to the pushed tag object rather than a mutable branch ref.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/release.yml Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/release.yml Outdated
Comment on lines +113 to +120
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()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .github/workflows/release.yml Outdated
set -euo pipefail
uv run python -m unittest discover -s tests -p "test_*.py"
./generate_models.sh --from-lock
git diff --exit-code

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85 gsmith85 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@gsmith85
gsmith85 force-pushed the feat/calver-release-workflows branch 3 times, most recently from 40bab0c to aec7f4a Compare November 18, 2026 23:35
@gsmith85
gsmith85 force-pushed the feat/calver-release-workflows branch from aec7f4a to 79a8c53 Compare November 19, 2026 04:09
@gsmith85
gsmith85 force-pushed the feat/calver-release-workflows branch from 79a8c53 to 2d49d7c Compare November 19, 2026 05:00

@damaz91 damaz91 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@damaz91
damaz91 merged commit 3e60a38 into main Nov 19, 2026
16 checks passed
@damaz91
damaz91 deleted the feat/calver-release-workflows branch November 19, 2026 08:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants