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).
One repository does everything (developer decision, 2026-11-16, ITL-1193):
metamorphic-labs/orcapod-python, a public repository, holds development (branches, pull
requests, review, CI, the Linear integration, the design log) and cuts the releases.
The Release workflow (.github/workflows/release.yml) is the only publishing route. The
developer dispatches it by hand on metamorphic-labs/orcapod-python, from main. It 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 metamorphic-labs, repository orcapod-python, workflow
release.yml and environment testpypi (TestPyPI) or pypi (PyPI); see One-time setup
below. An agent never runs the Release workflow, creates or pushes a tag, or changes a
setting, secret or environment.
History. Up to and including 0.3.0 (2026-11-17), releases were cut from
nauticalab/orcapod-python: main was pushed there by fast-forward at a release point, the
Release workflow ran there, and the tag was fetched back into metamorphic-labs
(ITL-1007). Every release tag up to v0.3.0 is also here, on the same commit; v0.2.0 (a
tag only, never published) exists only here and stays as it is.
- 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 main before the Release workflow runs:
-
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
metamorphic-labs, 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 runs the Release workflow:
- The full suite is green:
uv run pytest tests/passes on the commit to be released. - The release pull request is merged (
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, andgit statusis clean.- The version is free: the tag does not exist on
metamorphic-labs, and the version is on neither PyPI nor TestPyPI. - The Linear release is named (see Linear Release System): the open release of the
Linear release pipeline has the version
vX.Y.Z, and nothing merges intomainuntillinear-completehas finished. Not for a hotfix run, which leaves the open release as it is. - The security exceptions are reviewed: every exception in
docs/dev/security-exceptions.mdwhose advisory has a published fix is removed.
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
metamorphic-labs/orcapod-python(and onnauticalab/orcapod-python, the release repository up to0.3.0): 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, and the ruleset protect-release-tags forbids deleting a v* tag, so a hand-made
vX.Y.Z tag means that version can no longer be published by the workflow.
-
Run Release — go to Actions → Release → Run workflow in the GitHub UI, keep Use workflow from on
main, enter the version (e.g.0.4.0), optionally enter a branch name (defaults tomain), and click Run workflow. A leadingvis stripped automatically. Leave theskip_testscheckbox (labelled Skip the test jobs …) unchecked; it is an exception, described in Skipping the release tests below. The developer does this; no agent runs the workflow. -
Approve the PyPI deployment —
publish-pypiruns in thepypienvironment, which requires a reviewer: approve it oncepublish-testpypihas succeeded. -
CI takes over — the workflow runs the following jobs:
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); the tests are skipped only with
skip_tests - Build: normalises version (strips a leading
v), checks the golden release step and the release tags, 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 and a reviewer approves,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 (see Linear Release System)
- Pre-flight: branch validation, then tests on Python 3.11, 3.12 and 3.13 and license check (parallel after validation); the tests are skipped only with
The tag is created by the workflow in this repository; there is nothing to fetch back.
The Release workflow has a boolean input, skip_tests (a checkbox in the Run workflow form,
labelled Skip the test jobs …, default unchecked; developer, November 16, 2026, ITL-1188).
Checked, the test jobs (Python 3.11, 3.12 and 3.13) do not run; everything else does: branch validation,
the license check, the build with its golden checks, the tag, TestPyPI, PyPI and the GitHub
Release. Unchecked, the workflow is exactly what it was before the input existed.
This is an exception, for a pinch: the release tests take a long time and repeat what
Run Tests already ran on the same commit. Use it only when all of these hold:
- The exact commit being released (the tip of the Branch input) has green CI: the
Run Testsworkflow on that commit passed on Python 3.11, 3.12 and 3.13 (checksTests (3.11),Tests (3.12)andTests (3.13)). Check the commit id, not the branch name. - The pre-release checklist above holds, the full suite included.
- The developer chose it for this run. An agent never runs the Release workflow, with or without the option.
What the workflow guarantees:
- Only the input skips the tests. A test job that failed or was cancelled still stops the build and everything after it, as do a failed validation, license check or build.
- A run with the tests skipped says so: the build job writes a
Tests skippedwarning annotation and a run summary section naming who started the run (github.actor).
Every job after the tests carries its own condition. A GitHub job whose need was skipped is
itself skipped, and so is every job after it, unless its if names a status function; so
build, publish-testpypi, publish-pypi, linear-sync and linear-complete each check
the results of the jobs they need (!cancelled() && needs.<job>.result == 'success'), and
build accepts a skipped test only when skip_tests is set. A new job after the tests
needs the same.
On metamorphic-labs/orcapod-python and the package indexes; no agent changes settings,
secrets or environments:
- The environments
testpypiandpypi(Settings → Environments).pypirequires a reviewer. Give both a deployment branch policy that allowsmainonly, so that no workflow on another branch can request a publishing token. A hotfix release still passes it: the workflow runs frommain(Use workflow from) and only checks out the hotfix branch. - On pypi.org and test.pypi.org, an owner of the
orcapodproject opens Manage → Publishing and adds a GitHub trusted publisher with ownermetamorphic-labs, 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. Registered by the developer on 2026-11-16. Remove the entries that namenauticalaboncenauticalab/orcapod-pythonis retired. mainis protected by organization rulesets: today their rules are pull requests only, no force push (non-fast-forward) and no deletion. The rulesets for public repositories apply once the repository is public; check that they keep these three rules.- Release tags are protected with the ruleset
protect-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. - The
LINEAR_ACCESS_KEYrepository secret, for the Linear jobs (see Linear Release System). Codecov needs no secret (see Coverage uploads). - Before the first release cut here: the latest GitHub Release in this repository is
v0.1.2(the GitHub Release ofv0.3.0is onnauticalab), and the generated release notes start at the latest earlier Release. Create a GitHub Release forv0.3.0here (its notes copied fromnauticalab) so that the next notes start atv0.3.0, or edit the next Release's notes after the run.
The coverage jobs of Run Tests, Run PostgreSQL Tests and Run Specification Tests upload
to Codecov without a stored token (ITL-1193). The organization secret CODECOV_TOKEN is shared
with private and internal repositories only, so it would vanish when this repository became
public, and a token upload would then fail silently.
- Pushes,
workflow_dispatchand pull requests from a branch of this repository authenticate by GitHub OIDC: the job grants itselfid-token: write, and the action (use_oidc: true) sends a short-lived token signed by GitHub, which Codecov checks against GitHub's public keys. Nothing is stored here or set up in Codecov. - Pull requests from a fork get no OIDC token. The action detects the fork and uploads
without a token, under a
<user>:<branch>branch name, which Codecov accepts for a public repository. fail_ci_if_erroris on for every run except a pull request: a failed upload ofmainis seen, and a fork's tokenless upload can never fail its pull request.codecov.ymlholds Codecov's statuses until 7 uploads are in (codecov.notify.after_n_builds), so a pull request's statuses wait for the main test job's coverage. The comment there explains the number; change it with any change to the three workflows' matrices.
The developer keeps Codecov's organization setting token required for public repositories
at Required: then only OIDC (or a token) can upload to main, and only a fork's branch name
uploads tokenless. Turning it off would let anyone upload to any branch of every public
repository of the organization.
The spiral-integration job of Run Tests runs on every push to main and by hand
(workflow_dispatch) on metamorphic-labs/orcapod-python, never on pull requests. It runs
beside the test jobs, not after them, so its result comes in minutes. It authenticates to SpiralDB with a workload private key (ITL-1185): pyspiral reads
SPIRAL_CLIENT_ID (the workload id) and SPIRAL_PRIVATE_KEY (the private key as a JSON Web
Key) from the environment, signs a client assertion with the key, and requests a token from
https://auth.spiraldb.com/oauth/token with the client_credentials grant. It requests no
GitHub OIDC token: pyspiral's workload identity path posts a token exchange that the server
rejects. Client secrets are not used: the server no longer issues them. The job fails at its
first step, naming each missing setting, when one of the three below is not set or the key
is not a private JWK naming its kid. No agent creates, reads or sets any of them.
On metamorphic-labs/orcapod-python and in SpiralDB, the developer sets:
- The SpiralDB workload the job runs as (today
orcapod-gha) holds the editor role on the test project ("Orcapod testing"): the tests create, write, read and drop tables there. - A key pair registered for that workload. pyspiral's own CLI has no command for this; use
Studio or the newer SpiralDB CLI, in an environment of its own and never installed beside
pyspiral (both provide a top-level
spiralmodule):spiral workloads keys add <workload id> --kid <key id> --output -prints the private key as a JWK that names itskid. A PEM key is not accepted. - Repository secrets (
Settings → Secrets and variables → Actions → Secrets):SPIRAL_CLIENT_ID, the workload id (work_...), andSPIRAL_PRIVATE_KEY, the private JWK as one line of JSON. Keep the key file out of the repository and delete it once the secret is set. - Repository variable (
… → Variables):SPIRAL_PROJECT_ID, the id of the test project.
The server URL is fixed in the workflow (https://api.spiraldb.dev); the repository variable
SPIRAL_SERVER_URL and the secret SPIRAL_WORKLOAD_ID are not read and can be deleted.
To rotate the key: add a new key to the workload with a new kid, replace the
SPIRAL_PRIVATE_KEY secret with the new JWK, run Run Tests by hand on main and check that
spiral-integration passes, then remove the old key (spiral workloads keys rm). A workload
can hold several keys, so the job keeps working during the switch.
If the key may have been exposed (for example printed in a log), remove it from the workload
first (spiral workloads keys rm), so it stops signing in at once, then add a new key and
replace the secret as above. The job fails in between; that is the price of containment.
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.xpoints at the commit to release. The workflow checks that the Branch input exists in this repository and tags its tip. - 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 (unless skip_tests is
set; see Skipping the release tests), 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 | The tag cannot be deleted (protect-release-tags), and a new run or a re-run stops at the duplicate-tag guard: release the next patch version |
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.
Three jobs call linear/linear-release-action (pinned; it runs the Linear Release CLI) with
the LINEAR_ACCESS_KEY repository secret, the access key of one Linear release pipeline. Each
runs only when github.repository == 'metamorphic-labs/orcapod-python', so a fork's run skips
it, and none of them can block or undo a publish: no publish job depends on them. Up to
0.3.0 the two release jobs never ran (the Release workflow ran on nauticalab, where they are
skipped) and the Linear release was completed by hand. From the first release cut here they
run.
| Trigger | Workflow / Job | Command | What it does |
|---|---|---|---|
Push to main |
release-sync.yml / sync |
sync (no version) |
Scans the commits since the last synced commit for Linear issue ids and pull request numbers, and adds them to the pipeline's open release (today one with no version set) |
Release workflow build succeeds |
release.yml / linear-sync |
sync --version vX.Y.Z |
Targets the release whose version is vX.Y.Z, or creates one, and adds the commits since the last synced commit |
After publish-pypi succeeds |
release.yml / linear-complete |
complete --version vX.Y.Z |
Completes the release whose version is vX.Y.Z |
The workflow only syncs and completes the Linear release; any change of issue status that comes with a completed release is made by Linear, as the workspace configures it.
Before the first run, and every run after it: name the open release. Every push to main
adds its pull request to the open release, which has no version, and records that commit. The
CLI scans from the commit recorded by the latest release reachable from HEAD, exclusive
(<recorded>..HEAD), and creates no release for an empty range. A release of main's tip
therefore finds no new commit: without a release named vX.Y.Z, linear-sync creates nothing,
the open release holding the merged pull requests is left as it is, and linear-complete fails
to find vX.Y.Z. So, before running the
Release workflow, the developer sets the version of the pipeline's open release to vX.Y.Z in
Linear (pre-release checklist, item 6); linear-sync then targets it and linear-complete
completes it. From the rename until linear-complete has finished, merge nothing into main:
a push sync in between adds its pull request to the renamed release, which would mark it
shipped in vX.Y.Z although the build does not contain it. If one slips in, check whether the
build contains it (git merge-base --is-ancestor <its commit> vX.Y.Z): if it does, it stays in
vX.Y.Z; if not, move it and its issues back to the next open release by hand, and put back the
status of any issue the completed release moved. If a Linear job fails anyway, check publish-pypi first: if it succeeded, finish
the Linear release by hand; if not, recover publishing first (If a Run Fails Part-Way).
A hotfix run is different: never rename the open release for it. The open release holds
main's unreleased pull requests; naming it after the hotfix would mark them shipped in the
hotfix. The Linear jobs check out the workflow's ref (main), not the Branch input, so they
never scan the hotfix branch. When the push-to-main sync (release-sync.yml) has recorded
main's tip, the range is empty: linear-sync creates nothing and linear-complete fails, which
does not affect publishing. When it has not (it failed, or is still running), linear-sync
creates vX.Y.Z holding those unsynced main commits and linear-complete completes it. No
concurrency guard orders the two workflows, so after every hotfix run, check Linear for a
vX.Y.Z release. If there is one, for every main pull request and every issue it lists (the
CLI picks up issue ids from commit messages as well as pull requests, so an issue can be listed
without its pull request): move it to the open release by hand (the next push sync starts
after the commit the hotfix sync recorded, so it will not pick them up), and put back the
status of any issue that the completed release moved. Create or edit vX.Y.Z by hand if it should list the hotfix's own
issues. Syncing the hotfix commits themselves
would need the Linear jobs to check out the Branch input, a change to release.yml.
Setup: the LINEAR_ACCESS_KEY repository secret, holding the access key of the pipeline meant
for this repository's releases.