# Releasing

Maintainer runbook for cutting a `mononet` release to PyPI. Publishing uses
**PyPI Trusted Publishing** (OIDC) — no API tokens or stored secrets.

## One-time setup (maintainer, web UI)

Do this once before the first release.

1. **GitHub Environments.** In the repository settings, create two
   environments: `pypi` and `testpypi`.
2. **PyPI pending publisher** — at <https://pypi.org/manage/account/publishing/>,
   add a pending publisher:
   - PyPI Project Name: `mononet`
   - Owner: `davorrunje`
   - Repository name: `mononet`
   - Workflow name: `publish.yml`
   - Environment name: `pypi`
3. **TestPyPI pending publisher** — repeat at
   <https://test.pypi.org/manage/account/publishing/> with Environment name
   `testpypi`.

If any of these values is wrong, the first upload fails at the OIDC exchange
with a "not a trusted publisher" error.

## Version bumping

The version lives in `pyproject.toml` and is the single source of truth. Use
the **Bump Version** GitHub Action (Actions tab → Bump Version → Run workflow),
which runs `uv version --bump <type>` and opens a PR. Options:

| Bump | From `0.0.0a0` | Notes |
|------|----------------|-------|
| `alpha` | `0.0.0a1` | iterate the alpha |
| `beta` | `0.0.0b1` | |
| `rc` | `0.0.0rc1` | |
| `stable` | `0.0.0` | promote prerelease to final |
| `patch` | `0.0.1` | |
| `minor` | `0.1.0` | |
| `major` | `1.0.0` | |

`alpha`/`beta`/`rc`/`stable` only work standalone when the current version is
already a pre-release. From a stable version, bump a release component first
(`patch`/`minor`/`major`); a bare `alpha` bump from a stable version errors.

## Per-release flow

1. *(If benchmarks changed)* in a `gpu-*` devcontainer, run
   `./tools/execute-benchmarks.sh`, sanity-check `git diff docs/benchmarks/`,
   and commit the regenerated notebooks.
2. Run **Bump Version** with the desired bump type; merge the resulting PR into
   `main`.
3. *(Optional rehearsal)* Actions tab → **Publish** → Run workflow →
   `target: testpypi` (which is the default). Verify the project page on
   <https://test.pypi.org/project/mononet/> and a clean install:
   `pip install -i https://test.pypi.org/simple/ mononet==<version>`.
4. Create a **GitHub Release**: tag `v<version>` (e.g. `v0.0.0a0`), target the
   merge commit on `main`, mark it **pre-release** for alphas/betas/rcs, and
   write release notes.
5. Publishing the release fires the **Publish** workflow to real PyPI. It fails
   fast if the tag does not match the `pyproject.toml` version. The `v*.*.*`
   tag created by the release triggers the **Docs** workflow to deploy the
   versioned docs.

## Notes

- Publishing does not re-run the test matrix; releases are expected to be cut
  from a `main` whose `build.yml` checks are green.
- A real-PyPI upload cannot be replaced, only yanked. Use the TestPyPI
  rehearsal for first-of-its-kind releases.