Files
StarPunk/docs/standards/INDEX.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- 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>
2026-11-03 12:40:19 -07:00

2.7 KiB

Standards Index

Last Updated: 2026-11-03 (v2.10.1)

Standards for developing and releasing StarPunk. Folder rules are in ../DOCUMENTATION.md. All standards below were checked against the code at v2.10.1.

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)
utility-function-patterns.md Patterns for small helper functions
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; the full suite takes about 6 minutes, 5 of them in tests/test_migration_race_condition.py.
  • 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/ (none at present). Earlier versions of the standards above are in git history.