- 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>
55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
# Standards Index
|
|
|
|
**Last Updated**: 2026-11-03 (v2.10.1)
|
|
|
|
Standards for developing and releasing StarPunk. Folder rules are in
|
|
[../DOCUMENTATION.md](../DOCUMENTATION.md). All standards below were checked
|
|
against the code at v2.10.1.
|
|
|
|
## Active standards
|
|
|
|
| Standard | Covers |
|
|
|---|---|
|
|
| [development-setup.md](development-setup.md) | uv environment, `.env`, running the app with `DEV_MODE`, running the tests |
|
|
| [testing-checklist.md](testing-checklist.md) | What to test, test conventions, the CI test stage, protocol validation tools |
|
|
| [git-branching-strategy.md](git-branching-strategy.md) | Branches, commits, **the release process** (worktree, `merge --no-ff`, tag, CI, deploy), migrations |
|
|
| [versioning-strategy.md](versioning-strategy.md) | Choosing MAJOR / MINOR / PATCH |
|
|
| [version-implementation-guide.md](version-implementation-guide.md) | Where the version lives, changelog entry and design note format |
|
|
| [python-coding-standards.md](python-coding-standards.md) | Style, naming, and project patterns (config, database, outbound HTTP, errors, routes, workers) |
|
|
| [utility-function-patterns.md](utility-function-patterns.md) | Patterns for small helper functions |
|
|
| [cookie-naming-convention.md](cookie-naming-convention.md) | `starpunk_` cookie prefix and the cookies in use |
|
|
| [documentation-organization.md](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.
|
|
|
|
## Related
|
|
|
|
- [../architecture/](../architecture/): current system design
|
|
- [../decisions/](../decisions/): ADRs
|
|
- [../design/](../design/): per-release designs and reports
|
|
- [../projectplan/](../projectplan/): backlog and release plans
|