- architecture/: overview, technology stack, auth (OIDC + built-in IndieAuth), syndication (POSSE) rewritten; new database.md, deployment.md and indieweb-protocols.md; legacy stack marked historical - decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections (superseded auth ADRs, proposed -> accepted); INDEX rebuilt - design/: reconstructed the v1.6.0 documents the webmention code cites; reports for 18 v2 releases without a design folder; INDEX rebuilt - projectplan/: BACKLOG rewritten (shipped items removed, open issues from the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX - standards/: development setup (uv, tests, DEV_MODE), testing (CI test stage), git and release flow, versioning, coding standards, cookies - README, CLAUDE.md, .env.example (every setting the code reads, with defaults) brought up to date - 137 broken links repaired (old absolute paths, moved files); stale ADR references in code comments corrected (comments only) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.3 KiB
Version Implementation Guide
Status: Active Last Updated: 2026-11-03 (v2.10.1)
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__ = "2.10.1"
__version_info__ = (2, 10, 1)
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>