Files
StarPunk/docs/standards/version-implementation-guide.md
T
PhilandClaude Opus 5.5 ceef048003 docs: documentation review for v2.14.0
Architecture, README, standards, CLAUDE.md, settings reference, indexes,
backlog, release plans and CHANGELOG checked against the code at v2.14.0:
backfeed, notifications, counts line and web actions documented; test
policy (changed area locally, full suite in CI); stale versions, statuses
and links fixed; legacy and superseded docs moved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:51:57 -07:00

3.3 KiB

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. Git steps: git-branching-strategy.md.

Where the version lives

There is one source: starpunk/__init__.py, at the end of the file.

# 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/<version>).

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:

uv run python -c "import starpunk; print(starpunk.__version__)"

CHANGELOG.md

Keep a Changelog format. Add the new entry under ## [Unreleased], newest first:

## [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-<topic>.md, written alongside the change (rules in docs/DOCUMENTATION.md). Short and factual, for example docs/design/v2.8.1/2026-11-03-migration-lock.md:

# vX.Y.Z: <what changed>

## 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: <title>