diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..b3d0da20 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,117 @@ +# Releasing benchkit + +This document records the exact steps to publish a new release of benchkit. + +> **Naming note.** The PyPI distribution is `pybenchkit`; the import name and CLI +> are `benchkit`. The bare PyPI name `benchkit` is currently held by an +> unrelated project. Whenever this document says "PyPI project", we mean +> `pybenchkit`. + +Prereqs: +- You have push access to `open-s4c/benchkit` and to the `pybenchkit` PyPI project. +- `CHANGELOG.md` follows Keep a Changelog and Semantic Versioning. +- Version in `pyproject.toml` is maintained manually (PEP 440). +- CI is green on `main`. + +Versioning Tag format: `v0.X.Y` + +Date format: `YYYY-MM-DD`. + +--- + +## 1) Prepare the release + +1. Pick the version number `0.X.Y`. + +2. Update `CHANGELOG.md`: + - Add a new section `## [0.X.Y] - YYYY-MM-DD` under `[Unreleased]`. + - Move curated changes from `[Unreleased]` into `0.X.Y`. + +3. Bump the version in `pyproject.toml`: + ```toml + [project] + version = "0.X.Y" + ``` + +4. Sanity checks locally: + + ```bash + BENCHKIT_NO_PYLINT=yes ./scripts/all_checks.sh + pytest -q + git clean -ndx + git status + ``` + +5. Create a short-lived release branch and commit: + ```bash + git checkout -b release + git add -u + git commit -s -m "Release 0.X.Y" + git push -u origin release + ``` + +6. Open the corresponding PR on GitHub. When CI is green, merge. + +--- + +## 2) Tag the release + +After the PR is merged: + +```bash +git checkout main +git pull --prune +git tag -a "v0.X.Y" -m "Release v0.X.Y" +git push origin v0.X.Y +``` + +--- + +## 3) Build artifacts locally + +Use a fresh clone and venv to avoid leaking deps: + +```bash +git clone git@github.com:open-s4c/benchkit.git +cd benchkit/ +python3 -m venv .venv-release +. .venv-release/bin/activate +python3 -m pip install --upgrade pip +python3 -m pip install --upgrade build twine +python3 -m build # creates dist/*.whl and dist/*.tar.gz +python3 -m twine check dist/* +``` + +Quick inspection: + +* Confirm wheel exists (preferably `py3-none-any.whl` for pure Python). +* Confirm tarball contains only expected files (no `venv*/`, no `.venv*/`). + +--- + +## 4) Publish to PyPI + +```bash +# still in the .venv-release +python3 -m twine upload dist/* +``` + +You will need a `~/.pypirc` or to paste your `__token__` API token when prompted. +The token must be scoped to the `pybenchkit` PyPI project. + +--- + +## 5) Verify the release + +* PyPI page: [https://pypi.org/project/pybenchkit/](https://pypi.org/project/pybenchkit/) +* Clean venv install: + + ```bash + python3 -m venv /tmp/venv-verify && . /tmp/venv-verify/bin/activate + pip install -U pip + pip install pybenchkit==0.X.Y + benchkit --help + deactivate + ``` +* Check that README renders correctly on PyPI. +* Profit.