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>
96 lines
3.3 KiB
Markdown
96 lines
3.3 KiB
Markdown
# 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/<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:
|
|
|
|
```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-<topic>.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: <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>`
|