How a version gets from main to PyPI. The mechanics live in
.github/workflows/release.yml; this is the human checklist around it. The
package is published as sdr-dsp (PyPI normalises the underscore).
-
Register the PyPI project and its trusted publisher. On pypi.org, logged in as the owner: Your projects → Publishing → Add a new pending publisher:
- PyPI project name:
sdr-dsp - Owner:
LC-LinkousRepository:sdr_dsp_python - Workflow name:
release.ymlEnvironment name:pypi
This is OIDC "trusted publishing": GitHub proves to PyPI which workflow is running, and PyPI issues a short-lived token for that run. No API token is created, stored, or rotated. The pending publisher becomes the real one on the first successful publish.
- PyPI project name:
-
Create the
pypienvironment in the repo: Settings → Environments → New environment →pypi. Optionally add yourself as a required reviewer: then every publish waits for one click, which is cheap insurance against a mistyped tag. -
(Optional) Do the same on test.pypi.org and run the workflow once with
repository-url: https://test.pypi.org/legacy/added to the publish step, to see the whole path work before it is public. Remove the line after.
- Pick the version. While the major is 0, a minor bump (
0.x.0) is any release where a public function's behaviour or signature changed -- a newraiseon previously accepted input counts. A patch bump (0.3.x) is fixes that no correct caller can observe. - Edit
sdr_dsp/pyproject.toml:version = "X.Y.Z". This is the only place the version lives;sdr_dsp.__version__reads it from the installed metadata, and the release workflow refuses a tag that does not match it. If the development status changed, update the classifier. - Roll
CHANGELOG.md: rename## [Unreleased]to## [X.Y.Z] - YYYY-MM-DDwith a short summary paragraph on top (what kind of release this is, in three or four sentences), and open a fresh empty## [Unreleased]above it. - Run the gates locally from
sdr_dsp/-- the same ones CI runs:uv lock --check uv run pytest -q uv run ruff check . ../docs/dev_handbook uv run mypy uv run python ../docs/dev_handbook/generate_api_handbook.py --check ../docs/dev_handbook/sdr_dsp_API_HANDBOOK.md uv build && uv run --with twine twine check dist/*
- Commit and push to
main; wait fortests.ymlto go green on the full matrix. The release workflow re-runs the suite on one cell, not the matrix, so the matrix run onmainis the real multi-platform gate. - Rehearse the release on
main(optional but cheap): Actions → release → Run workflow, refmain,publishunchecked. The run performs every guard the real release will (suite, ruff, mypy, handbook--check, build,twine check, sdist contents) on that commit and uploads the wheel + sdist as a workflow artifact nameddist; nothing is published and no tag is needed. Download it andpip installthe wheel into a fresh venv to see the exact bytes that would ship. The only check it cannot do without a tag is tag == version, which step 7 does. - Tag and push the tag:
git tag -a vX.Y.Z -m "sdr_dsp X.Y.Z" git push origin vX.Y.Zrelease.ymlthen: checks the tag againstpyproject, re-runs the guards on the tagged commit, publishes via trusted publishing, and attaches the wheel and sdist to a GitHub release for the tag. If thepypienvironment has a reviewer, approve it in the Actions tab when it pauses. To publish by hand instead (or to retry after a failed publish job), Run workflow with refvX.Y.Zandpublishchecked; the workflow refusespublishon anything that is not av*tag. - Confirm:
pip install sdr-dsp==X.Y.Zin a fresh venv;python -c "import sdr_dsp; print(sdr_dsp.__version__)". - After the first release only: remove the "once the first PyPI release
is cut" hedges in
README.mdandsdr_dsp/README.md.
- The raw reference captures (
sample_data/hackrf_one/*.iq, 160 MB) are release assets on their own tag (v0.3.0-captures, theDEFAULT_RELEASEintools/fetch_sample_data.py). They change when a capture is re-taken, not when code changes, so they are not re-uploaded per version. To publish a new set:gh release create vX.Y.Z-captures sdr_dsp/sample_data/hackrf_one/*.iq, updateDEFAULT_RELEASE, and make sure each payload'ssdr_dsp:sha256in its sidecar matches (tools/fetch_sample_data.py --check). - The API handbook is regenerated and committed as part of the change that alters the API, not at release time; CI fails if it is stale.
- A tag pushed by mistake before
mainwas ready: delete it (git push --delete origin vX.Y.Z) before the publish job runs or is approved. Once a version is on PyPI it cannot be re-uploaded; the fix is the next patch version, andpip's view of the bad one can be hidden with yank on pypi.org (it stays installable by exact pin, which is what you want for anyone who already locked it). - The workflow refused the tag: the version in
pyproject.tomland the tag disagree. Fixpyproject, commit, re-tag.