# Version Implementation Guide **Status**: Active **Last Updated**: 2026-11-10 (v2.14.0) Where the version number lives and what to write for each release. Which number to pick: [versioning-strategy.md](versioning-strategy.md). Git steps: [git-branching-strategy.md](git-branching-strategy.md#release-process). ## Where the version lives There is one source: `starpunk/__init__.py`, at the end of the file. ```python # Package version (Semantic Versioning 2.0.0) # See docs/standards/versioning-strategy.md for details __version__ = "X.Y.Z" __version_info__ = (X, Y, Z) ``` Update both lines. Nothing else holds the number: there is no `pyproject.toml`, and the README doesn't state a version. At runtime: - `starpunk/config.py` sets `app.config["VERSION"]` from the `VERSION` environment variable, defaulting to `__version__`. Leave `VERSION` unset in deployments so the code's version is shown. - The version appears in the page footer, `/health`, `/admin/health` and the `User-Agent` of outgoing requests (`StarPunk/`). The git tag (`vX.Y.Z`) and the image tag CI publishes come from the tag you push, so they must match `__version__`. Check before tagging: ```bash uv run python -c "import starpunk; print(starpunk.__version__)" ``` ## CHANGELOG.md [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. Add the new entry under `## [Unreleased]`, newest first: ```markdown ## [2.10.1] - 2026-11-03 One optional sentence of context, e.g. which review or incident this release comes from, with links (ADR, spec). ### Security - ... ### Fixed - ... ``` - Sections, in this order, only those that apply: **Added**, **Changed**, **Deprecated**, **Removed**, **Fixed**, **Security**. - Write for the site owner: what they will notice and what they must do (new settings, behaviour changes), not which functions changed. - Name new settings in backticks, new migrations by number ("(migration 017)"), and link the ADR for a new feature. - Behaviour changes a user could trip over go first under **Changed**, in bold if they need action. ## Design note `docs/design/vX.Y.Z/YYYY-MM-DD-.md`, written alongside the change (rules in [docs/DOCUMENTATION.md](../DOCUMENTATION.md)). Short and factual, for example `docs/design/v2.8.1/2026-11-03-migration-lock.md`: ```markdown # vX.Y.Z: ## Incident / Context what was wrong or what was asked for ## Causes / Decision why, with references to the spec or ADR ## Fix / Changes what the code now does, file by file if useful ## Verification tests added, manual checks, before/after numbers ``` Releases whose design is fully recorded in an ADR (a new ADR, or an "Amendments" section, as v2.10.0 and v2.10.1 did in ADR-071) may skip the design note; the changelog then links the ADR. ## Code comments New or changed behaviour is often marked with the release that introduced it, e.g. `# Media types are case-insensitive (v2.10.1)`. This helps when reading the code next to the changelog; it is optional. ## Checklist - [ ] `__version__` and `__version_info__` updated in `starpunk/__init__.py` - [ ] `CHANGELOG.md` entry with today's date - [ ] Design note in `docs/design/vX.Y.Z/` (or ADR amendment) - [ ] `.env.example` updated for new settings - [ ] Commit subject ends with `(vX.Y.Z)`; tag is `vX.Y.Z`, annotated, message `vX.Y.Z: `