Files
StarPunk/docs/standards/INDEX.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

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

  • uv for environments, uv run for 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 every vX.Y.Z tag.
  • Every release: branch in a worktree, bump __version__ and __version_info__, changelog entry, design note (or ADR amendment), git merge --no-ff, annotated vX.Y.Z tag; 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.