Release Process

Release Process

The six sardine-cms-* packages release in lockstep under one vX.Y.Z tag. Claude/maintainer flow:

1. Bump version in the six pyproject.toml files (same value everywhere; tests/test_versions.py enforces lockstep). Reinstall the editable packages locally before running the gate — stale metadata fails the version test.
2. Close the ## Unreleased section of CHANGELOG.md under the new version with the date.
3. PR → green CI → squash merge.
4. Annotated tag on main: git tag -a vX.Y.Z -m "…" && git push origin vX.Y.Z (tags v* are protected — no deletion or moving).
5. release.yml builds once and publishes each package from its own GitHub environment via PyPI trusted publishing (OIDC, no long-lived tokens). skip-existing: true makes re-runs safe.

PyPI trusted publisher configuration (the part that lives on pypi.org)

Each project's Manage → Publishing page must have exactly one GitHub publisher row. All six share Owner ph7x-Systems, Repository sardine-cms, Workflow release.yml — and differ only in the environment (exact, lowercase):

PyPI project	Environment
sardine-cms-core	pypi-core
sardine-cms-validation	pypi-validation
sardine-cms-build	pypi-build
sardine-cms-cli	pypi-cli
sardine-cms-admin	pypi-admin
sardine-cms-theme-ph7x-reference	pypi-theme

A mismatched environment produces 403 Invalid API Token: OIDC scoped token is not valid for project … for that package while the correctly configured ones publish — this exact incident happened on v0.2.0.

Automatic fallback

The publish job tries OIDC first; on failure it retries with the repository secret PYPI_API_TOKEN (an account API token), so a publisher mismatch can never stall a release. Set or rotate it with:

az keyvault secret show --id <vault-secret-url> --query value -o tsv | gh secret set PYPI_API_TOKEN -R ph7x-Systems/sardine-cms

OIDC remains the primary path — keep the publisher table above correct so the fallback stays unused.

Emergency manual publish

If OIDC is blocked, a maintainer can publish the already-built artifacts with a short-lived account API token, then revoke it:

gh run download <release-run-id> -R ph7x-Systems/sardine-cms -n distributions -D dist
python3 -m twine upload --skip-existing dist/<package>-X.Y.Z*

Username __token__; never commit or share the token.