From 07de073a1a0626a8ab23e67af1ad3debe56da7ad Mon Sep 17 00:00:00 2001 From: Marc Balestreri Date: Tue, 10 Mar 2026 23:16:23 -0700 Subject: [PATCH 1/3] docs: add release process to Development.md --- DEVELOPMENT.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 7804c21..2d1dd55 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -15,6 +15,10 @@ - [Adding examples](#adding-examples) - [Creating a Pull Request](#creating-a-pull-request) - [Working with Jupyter Notebooks](#working-with-jupyter-notebooks) + - [Releasing a New Version](#releasing-a-new-version) + - [Prerequisites](#prerequisites-1) + - [Versioning](#versioning) + - [Release Steps](#release-steps) ## Introduction @@ -125,3 +129,62 @@ This library is packaged with examples that can be downloaded via the doc websit make jupyter ``` +## Releasing a New Version + +### Prerequisites + +1. **PyPI maintainer access**: You must be added as a maintainer on the [biolearn PyPI project](https://pypi.org/project/biolearn/). Contact an existing maintainer to be added. +2. **PyPI API token**: Generate a project-scoped API token at [pypi.org/manage/account/token](https://pypi.org/manage/account/token/). Scope it to the `biolearn` project only. +3. **Hatch**: Install the build/publish tool globally: + ```bash + pipx install hatch + ``` + +### Versioning + +This project uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) with the `hatch-vcs` plugin, which derives the package version from git tags automatically. + +- **PATCH** (e.g., 0.9.0 → 0.9.1): Bug fixes only +- **MINOR** (e.g., 0.9.1 → 0.10.0): New features, backwards compatible +- **MAJOR** (e.g., 0.10.0 → 1.0.0): Breaking API changes + +Tags use the `v` prefix (e.g., `v0.9.0`). You **must** tag before building — otherwise hatch produces a dev version. + +### Release Steps + +1. **Ensure master is clean and tests pass** + ```bash + git checkout master + git pull origin master + make test + ``` + +2. **Tag the release** + ```bash + git tag v0.X.Y + git push origin v0.X.Y + ``` + +3. **Build** + ```bash + hatch build -c + ``` + Verify the filenames in `dist/` show the correct version with no `dev` suffix. + +4. **Publish to PyPI** + ```bash + export HATCH_INDEX_USER=__token__ + export HATCH_INDEX_AUTH= + hatch publish + ``` + +5. **Build and publish documentation** + ```bash + source .venv/bin/activate + cd doc + make html + ``` + Copy the contents of `doc/_build/html/` into the [bio-learn.github.io](https://github.com/bio-learn/bio-learn.github.io) repo and push. + +**Note:** The Makefile has a `publish` target (`make publish`) but it references `.venv/bin/hatch` which may not be available. Use a globally installed `hatch` as described above. + From 49b12add7e1aa62eb22dfc79f5bade61e718175b Mon Sep 17 00:00:00 2001 From: Marc Balestreri Date: Wed, 25 Mar 2026 11:23:43 -0700 Subject: [PATCH 2/3] docs: fix pre-1.0 versioning description per review --- DEVELOPMENT.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 2d1dd55..356b0b1 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -144,9 +144,11 @@ This library is packaged with examples that can be downloaded via the doc websit This project uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) with the `hatch-vcs` plugin, which derives the package version from git tags automatically. -- **PATCH** (e.g., 0.9.0 → 0.9.1): Bug fixes only -- **MINOR** (e.g., 0.9.1 → 0.10.0): New features, backwards compatible -- **MAJOR** (e.g., 0.10.0 → 1.0.0): Breaking API changes +Biolearn is currently pre-1.0, meaning the API is not yet considered stable. In the `0.x` range: + +- **PATCH** (e.g., 0.9.0 → 0.9.1): Bug fixes and small additions +- **MINOR** (e.g., 0.9.1 → 0.10.0): New features, may include breaking changes +- **MAJOR** (e.g., 0.10.0 → 1.0.0): Major release, stable API with full feature completeness Tags use the `v` prefix (e.g., `v0.9.0`). You **must** tag before building — otherwise hatch produces a dev version. From 6bd8a08cd5b225be123c2e362ee7be0484704304 Mon Sep 17 00:00:00 2001 From: Marc Balestreri Date: Wed, 25 Mar 2026 11:42:26 -0700 Subject: [PATCH 3/3] docs: replace 'stable API' with library-specific language in versioning --- DEVELOPMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 356b0b1..f3011f0 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -144,11 +144,11 @@ This library is packaged with examples that can be downloaded via the doc websit This project uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) with the `hatch-vcs` plugin, which derives the package version from git tags automatically. -Biolearn is currently pre-1.0, meaning the API is not yet considered stable. In the `0.x` range: +Biolearn is currently pre-1.0, meaning the library is not yet considered stable. In the `0.x` range: - **PATCH** (e.g., 0.9.0 → 0.9.1): Bug fixes and small additions - **MINOR** (e.g., 0.9.1 → 0.10.0): New features, may include breaking changes -- **MAJOR** (e.g., 0.10.0 → 1.0.0): Major release, stable API with full feature completeness +- **MAJOR** (e.g., 0.10.0 → 1.0.0): Major release, stable library with comprehensive clock and feature coverage Tags use the `v` prefix (e.g., `v0.9.0`). You **must** tag before building — otherwise hatch produces a dev version.