1
# Commit Conventions
2
3
Standing rules for commit messages, branch names, and PR descriptions. Apply these
4
whenever creating a commit, branch, or PR in this repo — the goal is a git history and
5
PR list that's searchable and skimmable, not a formality.
6
7
## Commit message format
8
9
Follow [Conventional Commits](https://www.conventionalcommits.org/):
10
11
```
12
<type>(<optional scope>): <short summary, imperative mood, no trailing period>
13
14
<optional body — why, not just what, wrapped at ~72 chars>
15
16
<optional footer(s) — BREAKING CHANGE:, Fixes #123, Co-Authored-By:>
17
```
18
19
### Types
20
21
| type | use for |
22
|---|---|
23
| `feat` | a new feature or user-visible capability |
24
| `fix` | a bug fix |
25
| `docs` | documentation only |
26
| `style` | formatting, whitespace, no logic change |
27
| `refactor` | code change that neither fixes a bug nor adds a feature |
28
| `perf` | a performance improvement |
29
| `test` | adding or correcting tests, no production code change |
30
| `build` | build system, dependencies, packaging |
31
| `ci` | CI configuration/scripts |
32
| `chore` | maintenance that doesn't fit elsewhere (e.g. bumping a version) |
33
| `revert` | reverts a previous commit |
34
35
### Rules
36
37
- Summary line: imperative mood ("add", "fix", "remove" — not "added"/"fixes"), lower
38
  case after the type, no trailing period, ideally ≤ 72 characters.
39
- Scope (optional) is the affected area in parentheses, e.g. `feat(auth): ...`,
40
  `fix(billing): ...`. Omit if the change is repo-wide or scope is ambiguous.
41
- Body explains **why**, not a restatement of the diff — the diff already shows what
42
  changed. Use the body for context a future reader won't get from the code alone.
43
- Breaking changes: add a `BREAKING CHANGE:` footer describing the break and, if
44
  applicable, the migration path. Also prefix the type/scope with `!`, e.g.
45
  `feat(api)!: ...`.
46
- One logical change per commit. A commit that mixes an unrelated formatting pass with
47
  a behavior change should be split.
48
- Reference issues in the footer (`Fixes #123`, `Refs #456`), not the summary line.
49
50
### Examples
51
52
```
53
feat(search): add fuzzy matching to package search
54
55
Exact-match search was returning zero results for common typos
56
(e.g. "revewer" for "reviewer"). Adds a Levenshtein-distance fallback
57
when the exact query returns nothing.
58
59
Fixes #212
60
```
61
62
```
63
fix(cli): handle missing OPENAGENTS_REGISTRY env var
64
65
fix!: remove deprecated `--token` flag from `add` command
66
67
BREAKING CHANGE: `openagents add` no longer accepts `--token`; use
68
`OPENAGENTS_REGISTRY` with credentials embedded in the URL, or a
69
future `openagents login` command.
70
```
71
72
## Branch naming
73
74
```
75
<type>/<short-kebab-case-description>
76
```
77
78
Use the same `type` vocabulary as commits. Examples: `feat/fuzzy-search`,
79
`fix/cli-missing-env-var`, `refactor/catalog-loader`. Include an issue number when one
80
exists: `fix/212-search-typos`.
81
82
Avoid personal-name or date-based branch names (`zach/wip`, `2026-09-09`) — the branch
83
name should describe the change, not the author or timestamp (git already tracks both).
84
85
## PR descriptions
86
87
Use `templates/pr.md`. Every PR description should let a reviewer understand *what
88
changed and why* without reading the full diff first, and should describe how the
89
change was verified.
90
91
## When these rules don't fit
92
93
Hotfixes under genuine time pressure, or single-commit auto-generated PRs (e.g. a
94
dependency bot), may skip body/footer detail — but still use a correctly-typed summary
95
line so the history stays searchable by type.
96