- 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>
2.7 KiB
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
uvfor environments,uv runfor every command.- Tests need
SESSION_SECRET; the full suite takes about 6 minutes, 5 of them intests/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, 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/ (none at
present). 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