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>
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.pysetsapp.config["VERSION"]from theVERSIONenvironment variable, defaulting to__version__. LeaveVERSIONunset in deployments so the code's version is shown.- The version appears in the page footer,
/health,/admin/healthand theUser-Agentof 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 instarpunk/__init__.pyCHANGELOG.mdentry with today's date- Design note in
docs/design/vX.Y.Z/(or ADR amendment) .env.exampleupdated for new settings- Commit subject ends with
(vX.Y.Z); tag isvX.Y.Z, annotated, messagevX.Y.Z: <title>