1. Format
<type>(<scope>): <subject>
<body>
- subject: imperative mood, lowercase, no period, under 72 characters
- scope: optional, names the area changed (e.g.
cli, auth, explorer)
- body: optional, explains why not what, wrapped at 72 characters
2. Types
| Type |
When to use |
feat |
A new feature or capability |
fix |
A bug fix |
test |
Adding or updating tests only |
docs |
Documentation changes only |
refactor |
Code restructuring with no behavior change |
chore |
Maintenance — deps, CI, tooling, config |
perf |
Performance improvement with no behavior change |
style |
Formatting, whitespace, linting — no logic change |
3. Scope
Use the most specific component name that applies:
- CLI commands:
cli, ship, skim, scan, follow
- Libraries:
auth, pds, lexicon, brand
- Infrastructure:
ci, deps, build
- Documentation:
docs, readme, skill
Omit scope if the change spans multiple areas.
4. Examples
feat(scan): add tag filtering for skill discovery
fix(auth): handle expired OAuth sessions gracefully
test(ship): add validation tests for --kind flag
docs(skill): document vit scan flags and output format
refactor(pds): extract DID resolution into shared helper
chore(deps): update bun to 1.3.10
perf(skim): batch PDS queries for followed accounts
style(cli): normalize whitespace in help output
5. Breaking Changes
Add ! after type/scope and a BREAKING CHANGE: footer:
feat(auth)!: require OAuth for all PDS operations
BREAKING CHANGE: Basic auth is no longer supported. Users must run
`vit login <handle>` to authenticate via OAuth.
6. Multi-line Bodies
When the why matters, use the body:
fix(skim): deduplicate caps from multi-PDS resolution
The handle-to-DID resolution could return records from both the
primary and mirror PDS, causing duplicate caps in skim output.
Filter by URI uniqueness before display.
1---2name: semantic-commits3description: Guides agents to write conventional commit messages with correct types, scopes, and formatting. Activates when committing code or writing commit messages.4---56## 1. Format78```9<type>(<scope>): <subject>1011<body>12```1314- **subject**: imperative mood, lowercase, no period, under 72 characters15- **scope**: optional, names the area changed (e.g. `cli`, `auth`, `explorer`)16- **body**: optional, explains *why* not *what*, wrapped at 72 characters1718## 2. Types1920| Type | When to use |21|------|------------|22| `feat` | A new feature or capability |23| `fix` | A bug fix |24| `test` | Adding or updating tests only |25| `docs` | Documentation changes only |26| `refactor` | Code restructuring with no behavior change |27| `chore` | Maintenance — deps, CI, tooling, config |28| `perf` | Performance improvement with no behavior change |29| `style` | Formatting, whitespace, linting — no logic change |3031## 3. Scope3233Use the most specific component name that applies:3435- CLI commands: `cli`, `ship`, `skim`, `scan`, `follow`36- Libraries: `auth`, `pds`, `lexicon`, `brand`37- Infrastructure: `ci`, `deps`, `build`38- Documentation: `docs`, `readme`, `skill`3940Omit scope if the change spans multiple areas.4142## 4. Examples4344```45feat(scan): add tag filtering for skill discovery46fix(auth): handle expired OAuth sessions gracefully47test(ship): add validation tests for --kind flag48docs(skill): document vit scan flags and output format49refactor(pds): extract DID resolution into shared helper50chore(deps): update bun to 1.3.1051perf(skim): batch PDS queries for followed accounts52style(cli): normalize whitespace in help output53```5455## 5. Breaking Changes5657Add `!` after type/scope and a `BREAKING CHANGE:` footer:5859```60feat(auth)!: require OAuth for all PDS operations6162BREAKING CHANGE: Basic auth is no longer supported. Users must run63`vit login <handle>` to authenticate via OAuth.64```6566## 6. Multi-line Bodies6768When the *why* matters, use the body:6970```71fix(skim): deduplicate caps from multi-PDS resolution7273The handle-to-DID resolution could return records from both the74primary and mirror PDS, causing duplicate caps in skim output.75Filter by URI uniqueness before display.76```
solpbc