| name | commits |
| description | Use when picking a branch name, staging files, or writing a commit message — covers branch conventions, the project's Conventional Commits format with the scope vocabulary observed in history, and the documentation-update gate that fires before every commit (`docs/*`, `README.md`, godoc, Helm values). |
Commits
Branches
| Use | Form |
|---|
| Feature work | feature/<short-slug> |
| Bug fix tied to an issue | fix/<NN>-<short-slug> (NN = issue number) |
| Codex / agent branches | codex/<slug> |
| Release / deploy | bot-owned — never push manually |
Branch from main, not development (no development branch in this repo). Keep one branch focused on one change. If you find yourself fixing two unrelated things, that's two branches.
Commit messages — Conventional Commits
<type>(<scope>): <imperative subject, lowercase, no trailing period>
<optional body — explain *why*, not *what*. Wrap at ~72 cols.>
Types observed in history: feat, fix, chore, docs, test, perf. The repo doesn't use refactor, style, or ci as types — ci is a scope.
Scopes (use one of these when it fits; invent sparingly):
| Layer | Scopes |
|---|
| Backend domain | api, auth, oidc, db, metadata, indexer, downloader, importer, recommender, scheduler, notifier, series, author, abs, calibre, telemetry, opds, httpsec |
| Cross-cutting | ci, release, deploy, lint, deps / deps-dev, migrate, sync, scanner, search |
| Other | test, docs, web |
Issue link in the subject: append (#NN) — e.g. fix(indexer): strip possessive author prefix from title before relevance matching (#446).
Reserved: chore(deploy): promote bindery to vX.Y.Z [skip ci] is bot-only. Never include [skip ci] in human or agent commits — it bypasses CI and CI is the gate.
Subject examples from real history:
feat(oidc): test discovery button surfaces IdP errors before login (#460)fix(recommender): don't gate author-new / series / genre-popular on ratings countperf(author): parallelize author work discovery and searchestest(downloader): cover download client edge-case matrix (#451)docs(series): document enhanced hardcover series workflow
Documentation-update gate
Before staging the commit, walk the diff and update the matching docs in the same commit (or at minimum the same PR — never a follow-up).
| If your diff touches… | Update… |
|---|
| Env vars, config, startup flags, upgrade path | docs/DEPLOYMENT.md |
| Auth modes / OIDC / proxy auth | docs/auth-multiuser.md, docs/auth-oidc.md, docs/auth-proxy.md, docs/troubleshooting-auth.md as applicable |
| ABS import flow | docs/abs_import.md (+ docs/ABS-Import-Wiki.md for user-facing changes) |
| Hardcover / series feature | docs/Hardcover-Series-Wiki.md |
| Upgrade-from-v1 path | docs/upgrade-v2.md |
| Multi-user behaviour | docs/multi-user.md |
| Feature surface advertised at top level | README.md |
| Helm chart values, env, image config | charts/bindery/values.yaml |
| New exported Go symbol with non-obvious behaviour | godoc comment on the symbol |
| Agent process / lifecycle / skill triggers | AGENTS.md (only when the agent contract genuinely changes — don't routinely touch) |
Rule of thumb: the entire docs/ directory and README.md are maintained at every commit — they should never lag behind the code. AGENTS.md is updated only when contributor / agent process actually shifts. CONTRIBUTING.md is human-maintained — don't auto-edit unless the user asks.
Pure refactors with no behaviour change require no doc update.
Out of scope (release-time only)
CHANGELOG.md sections are authored at tag/deploy time, not at commit time. Don't add an [Unreleased] entry; don't modify versioned sections. The tag-release skill covers CHANGELOG authoring when cutting ## [vX.Y.Z].
Don't
- Don't include
[skip ci] in human or agent commits.
- Don't
--amend after a hook failure — the commit didn't happen, so amend modifies the previous one. Re-stage and create a new commit.
