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>
2.7 KiB
2.7 KiB
Standards Index
Last Updated: 2026-11-10 (v2.14.0)
Standards for developing and releasing StarPunk. Folder rules are in ../DOCUMENTATION.md. All standards below were checked against the code at v2.14.0.
Active standards
| Standard | Covers |
|---|---|
| development-setup.md | uv environment, .env, running the app with DEV_MODE, running the tests |
| testing-checklist.md | What to test, test conventions, the CI test stage, protocol validation tools |
| git-branching-strategy.md | Branches, commits, the release process (worktree, merge --no-ff, tag, CI, deploy), migrations |
| versioning-strategy.md | Choosing MAJOR / MINOR / PATCH |
| version-implementation-guide.md | Where the version lives, changelog entry and design note format |
| python-coding-standards.md | Style, naming, and project patterns (config, database, outbound HTTP, errors, routes, workers) |
| cookie-naming-convention.md | starpunk_ cookie prefix and the cookies in use |
| documentation-organization.md | Templates and conventions for docs (folder rules: DOCUMENTATION.md) |
Where to start
- New to the code: development-setup → python-coding-standards → testing-checklist.
- Making a release: git-branching-strategy (release process), which links to versioning-strategy and version-implementation-guide.
- Writing an ADR or design note: documentation-organization.
Key rules in brief
uvfor environments,uv runfor every command.- Tests need
SESSION_SECRET. Locally, run only the tests for the area you changed; CI runs the full suite (about 6 minutes) on everyvX.Y.Ztag. - Every release: branch in a worktree, bump
__version__and__version_info__, changelog entry, design note (or ADR amendment),git merge --no-ff, annotatedvX.Y.Ztag; CI tests and publishes the image; deploy from the Ansible repository; back up the database first when there is a migration. - Formatters and linters are available but not enforced; match the file you are editing.
Deprecated standards
Standards that no longer apply move to DEPRECATED/:
utility-function-patterns.md
(superseded by python-coding-standards.md, 2026-11-10). Earlier versions of the standards above are in git history.
Related
- ../architecture/: current system design
- ../decisions/: ADRs
- ../design/: per-release designs and reports
- ../projectplan/: backlog and release plans