This document describes how to cut a release of orcapod.
Orcapod is published on public PyPI as orcapod, under
the MIT License (developer decision, 2026-11-10; the license is applied from 0.2.0). Users
install it with pip install orcapod or uv add orcapod. 0.2.0 was cut as a tag only
(developer decision, 2026-11-10); 0.3.0 is the first release published to PyPI from this
repository.
Two repositories take part (developer decision, 2026-11-12, ITL-1007):
| Repository | Role |
|---|---|
metamorphic-labs/orcapod-python |
All development: branches, pull requests, review, CI, Linear integration, the design log. |
nauticalab/orcapod-python (public) |
Releases only: receives main by fast-forward push at a release point, and runs the Release workflow. |
The Release workflow (.github/workflows/release.yml) is the only publishing route. It runs
only when dispatched by hand on nauticalab/orcapod-python, uploads to TestPyPI first and then
to PyPI, and authenticates to both through OIDC trusted publishing: the workflow uses no API
token. That requires, on each index, a trusted publisher for the orcapod project naming owner
nauticalab, repository orcapod-python, workflow release.yml and environment testpypi
(TestPyPI) or pypi (PyPI); see One-time setup below.
- All development happens on feature branches off
main. - There are no long-lived branches (the historical
devbranch has been retired). - No back-merges are needed.
Do these on metamorphic-labs main before anything is pushed:
-
Update
CHANGELOG.mdin a release pull request, the only kind of pull request that edits it. Feature pull requests addchangelog.d/<ISSUE-ID>.mdfragments instead (seechangelog.d/README.md).-
Fold the fragments into the section of the version being released:
uv run python scripts/assemble_changelog.py --version X.Y.ZThis appends each fragment's text to the matching category of
## [X.Y.Z](in order of issue id, without moving the lines already there), creates the section or a category if it is missing, and deletes the fragments. It stops without changing anything if a fragment is malformed;--checkreports the same problems without folding. Commit the changedCHANGELOG.mdand the deleted fragments together;changelog.d/README.mdstays. -
Set the section's heading to the version being released and its date (
## [X.Y.Z] — YYYY-MM-DD), and make sure breaking changes carry migration notes.
The GitHub Release body is generated from PR titles;
CHANGELOG.mdis the curated record. -
-
Record the release in the golden history, in the same release pull request, as its last change (see Golden hash values below):
TZ=UTC uv run python tests/test_hashing/golden/generate_golden_hashes.py --release X.Y.ZRelease dates are UTC days: the release revision records the date of the local clock, so run the script with
TZ=UTCand check that the date it records equals the date in theCHANGELOG.mdheading. It appends the release revision to thegoldenhistory of the current data context's manifest, writes its digest underreleasesinsrc/orcapod/contexts/released_manifests.json, and at the data context's first release setsreleased_inand themanifestpin. It computes no hash and refuses a version already released. Commit both files with the release pull request; the release is tagged on a commit that contains them. The Release workflow's build job checks this before it creates the tag (scripts/check_golden_tags.py --release-version X.Y.Z) and stops if the release is not recorded, or if a golden file was added after the release step (the release revision must be the last revision when the commit is tagged). It also runs the tag check (scripts/check_golden_tags.py) there, so a branch that changed what an earlier release of the data context shipped is not released. Tags of earlier data contexts are not checked, so the first release of a data context passes with nothing to check. -
Check that
mainis green — theRun Testsworkflow on the commit you are releasing. The Release workflow re-runs the unit tests on Python 3.11, 3.12 and 3.13 and the license check, but not the PostgreSQL or SpiralDB integration jobs. -
Check the version is free — the tag must not exist on origin, and the version must not exist on PyPI or TestPyPI; neither index allows a version to be uploaded twice, even after it is deleted.
Per-release checklists live in docs/dev/plans/ (for example
2026-11-09-v0.2-release-checklist.md, 2026-11-15-v0.3-release-checklist.md).
All of these hold before the developer is asked for the go:
- The full suite is green:
uv run pytest tests/passes on the commit to be pushed. - The release pull request is merged on
metamorphic-labs(CHANGELOG.mdfolded, section dated,changelog.d/fragments deleted). - The golden release step is done:
contexts/released_manifests.jsonhas the current data context'sreleasesline for this version and a pinnedmanifest, and the golden hash tests and the data context tests pass unchanged. mainis green onmetamorphic-labs, andgit statusis clean.- The version is free: the tag does not exist on
nauticalab, and the version is on neither PyPI nor TestPyPI.
Developer decisions, November 15, 2026 (ITL-946); the mechanism and what each check protects
against are in docs/reference/golden-hashes.md.
- A golden file that a release listed never changes, and is never removed or renamed.
- New golden values can be added in any release, a patch included.
- Any change to a released golden value, a logical type's own identifier change included, needs a new data context version. A new data context version ships only in a minor release (before 1.0) or a major one, never in a patch.
- When a new data context starts, the old context's golden files and code move to
orcapod-sanctuary; this repository carries only the current context's golden folder. - Release tags are protected on both
metamorphic-labs/orcapod-pythonandnauticalab/orcapod-python: the repository rulesetprotect-release-tags(targetrefs/tags/v*; rules deletion, update and non-fast-forward; no bypass actors) is in place since 2026-11-15. Av*tag can be created, as the Release workflow does, but never moved or deleted. This is a precondition of the CI tag check (scripts/check_golden_tags.py), which compares HEAD with every release tag of the current data context. Agents never change repository settings.
Releases are triggered from the GitHub Actions UI — no manual git tag step required.
Do not create the release tag by hand: the build job aborts when the tag already exists
on origin, so a hand-made vX.Y.Z tag means that version can no longer be published by the
workflow until the tag is deleted.
-
Push
maintonauticalabas a fast-forward, on the developer's explicit go only. A push to a public repository cannot be undone, so no agent does this on its own.git remote add nauticalab https://github.com/nauticalab/orcapod-python.git # once git fetch nauticalab git merge-base --is-ancestor nauticalab/main main && echo "fast-forward" # must print it git push nauticalab main:main # no --forceNever a squash, never a pull request: commit ids must stay identical in both repositories, because the version comes from the tag (
hatch-vcs). Never push thev0.2.0tag (or any tag): the Release workflow creates the release tag onnauticalab. The push also replaces the workflowsnauticalabcarries (its oldtests.ymlis deleted by it, asmainremoved that file). -
Run Release on
nauticalab— go to Actions → Release → Run workflow in the GitHub UI, enter the version (e.g.0.3.0), optionally enter a branch name (defaults tomain), and click Run workflow. A leadingvis stripped automatically. -
CI takes over — the workflow runs the following jobs automatically:
validate-branch ─┬─ test ──────────┐ └─ license-check ──┤─ build ─┬─ publish-testpypi ─ publish-pypi ─┐ └─ linear-sync ──────────────────────┴─ linear-complete- Pre-flight: branch validation, then tests on Python 3.11, 3.12 and 3.13 and license check (parallel after validation)
- Build: normalises version (strips a leading
v), creates the local tag, builds wheel + sdist withuv build, aborts if the tag already exists on origin, pushes the tag, uploadsdist/as an artifact - TestPyPI: in the
testpypienvironment,uv publish --publish-url https://test.pypi.org/legacy/ dist/*with an OIDC token (id-token: write) — a staging upload - PyPI: in the
pypienvironment, after TestPyPI succeeds,uv publish dist/*with an OIDC token, then creates the GitHub Release for the tag with generated release notes and the dist files attached - Linear:
linear-syncstarts immediately after build (parallel to publish);linear-completeruns after both PyPI publish and linear-sync succeed
-
Fetch the tag back into
metamorphic-labsonce the run has succeeded:git fetch nauticalab --tags git push origin vX.Y.Zmetamorphic-labsthen holds the same tag on the same commit.
On nauticalab/orcapod-python and the package indexes; no agent changes settings, secrets or
environments:
- Create the environments
testpypiandpypi(Settings → Environments). - On pypi.org and test.pypi.org, an owner of the
orcapodproject opens Manage → Publishing and adds a GitHub trusted publisher with ownernauticalab, repositoryorcapod-python, workflowrelease.ymland environmentpypi(PyPI) ortestpypi(TestPyPI). An upload from a repository that no trusted publisher names is rejected, which failspublish-testpypiafter the tag has been pushed. Remove the entries that namemetamorphic-labs, if any. - Protect
mainonnauticalab(no force push, no deletion). It is written only by the fast-forward push above. - Protect release tags on both
metamorphic-labs/orcapod-pythonandnauticalab/orcapod-pythonwith the rulesetprotect-release-tags(targetrefs/tags/v*; deletion, update, non-fast-forward; no bypass actors), so the golden tag check has a fixed anchor (ITL-946). Done on 2026-11-15. - Optional: set
CODECOV_TOKENthere. The Codecov, SpiralDB and Linear jobs run only onmetamorphic-labsand are skipped onnauticalab.
Release candidates (e.g. 0.1.0rc1) follow exactly the same path — enter the version in the
workflow input. PyPI handles the stable vs pre-release distinction natively:
pip install orcapod— installs the latest stable release onlypip install --pre orcapod— installs the latest release including pre-releases
To release from a branch other than main — for example, a maintenance branch carrying
a critical patch — enter the branch name in the Branch field when triggering the
workflow.
Example: cutting v0.1.1 from hotfix/0.1.x:
- Make sure
hotfix/0.1.xonnauticalabpoints at the commit to release. The workflow resolves the Branch input only there and tags its tip. If the branch is missing or behind, fast-forward it (on the developer's explicit go only, never with--force):git push nauticalab hotfix/0.1.x:hotfix/0.1.x - Trigger the release workflow — go to Actions → Release → Run workflow
- In the Use workflow from dropdown, keep
mainselected (so the workflow version includes theBranchfield — do not selecthotfix/0.1.xhere) - Set Version to
0.1.1 - Set Branch to
hotfix/0.1.x - Click Run workflow
The workflow will confirm the branch exists, run tests against it, create the v0.1.1
tag at its tip, and publish to TestPyPI and PyPI — identical to a normal release.
The build job pushes the vX.Y.Z tag to origin before anything is published, so a
failure in a later job leaves the tag behind.
| Failed job | State left behind | Recovery |
|---|---|---|
test or license-check |
Nothing | Fix on main, trigger a new run |
build, before "Push release tag" |
Nothing | Fix, trigger a new run |
build, after "Push release tag" |
Tag on origin, no artifact | Delete the tag (git push origin :refs/tags/vX.Y.Z), then trigger a new run |
publish-testpypi |
Tag on origin | Use Re-run failed jobs on the same run — do not start a new run, which would fail creating a tag that already exists |
publish-pypi |
Tag on origin, version on TestPyPI | Use Re-run failed jobs. If the upload to PyPI itself partly succeeded, the version is burned: release the next patch version instead |
linear-sync |
Unknown: it needs only build and runs in parallel with publishing, so it can fail before anything is published |
Check publish-testpypi and publish-pypi first and recover them by their rows above. Then re-run linear-sync; it does not affect publishing |
linear-complete |
Release is published (it runs only after publish-pypi and linear-sync succeed) |
Re-run the failed job; it does not affect publishing |
Never delete a tag whose version has been published to any package index.
v0.1.3 and v0.1.4 were cut from a maintenance branch and are not ancestors of
main; git describe on main therefore reports a distance from v0.1.2. This does not
affect a release from main, because the workflow creates the release tag on the commit
being built and hatch-vcs reads that tag. The fix those two releases carried is on
main. The commit tagged v0.1.4 is reachable only through its tag.
| Release type | Tag format | Example |
|---|---|---|
| Stable | vMAJOR.MINOR.PATCH |
v0.1.0 |
| Release candidate | vMAJOR.MINOR.PATCHrcN |
v0.1.0rc1 |
| Alpha | vMAJOR.MINOR.PATCHaN |
v0.1.0a1 |
| Beta | vMAJOR.MINOR.PATCHbN |
v0.1.0b1 |
The workflow input accepts any of the above (with or without a leading v). The version is
derived from the git tag by hatch-vcs (dynamic = ["version"] in pyproject.toml) — no
manual version bump is needed.
Linear is wired to the development repository only. release-sync.yml and the linear-sync and
linear-complete jobs of release.yml run only when
github.repository == 'metamorphic-labs/orcapod-python'; on nauticalab they are skipped, which
does not block or fail the release (no publish job depends on them). They call
linear/linear-release-action and transition the issues in "Merged" status to "Done".
| Trigger | Workflow / Job | Action | Effect |
|---|---|---|---|
Push to main (metamorphic-labs) |
release-sync.yml / sync |
sync (no version) |
Associates the merged PR with the open Linear release draft |
Release workflow build succeeds (metamorphic-labs only) |
release.yml / linear-sync |
sync --version <tag> |
Finalises the commit set for the version |
After publish-pypi succeeds (metamorphic-labs only) |
release.yml / linear-complete |
complete --version <tag> |
Marks the release done in Linear |
Because the Release workflow runs on nauticalab, these jobs do not run for a release at all
today; completing the Linear release is a manual step until the developer decides otherwise
(the issue ITL-1007 notes this "needs more thought"). Setup on metamorphic-labs: the
LINEAR_ACCESS_KEY repo secret (the organisation's Linear access key) and a Linear release
configured in the workspace.