Conventional Commits
Produce commits a future maintainer can trust: atomic, well-scoped, and explained.
Protocol
- Survey before staging. Run
git status and git diff (both staged and unstaged). Never commit blind.
- Split unrelated work. If the diff mixes concerns (a bugfix plus a refactor plus a config tweak), stage and commit them separately. One logical change per commit.
- Choose the type from:
feat, fix, refactor, perf, docs, test, build, ci, chore. When two apply, pick the one that matches the intent of the change, not its file types.
- Write the subject line.
- Format:
type(scope): imperative summary under 72 characters
- Scope is the module or area touched, only when it adds clarity
- Imperative mood: "add", "fix", "remove", never "added" or "adds"
- Write the body only when the diff cannot speak for itself. The body answers why: what problem existed, why this approach. Wrap at 72 characters.
- Verify before committing. If the repo has a test or lint command, run it on the staged state first.
Never
- Never commit secrets, keys,
.env files, or credentials. Check the diff for anything that looks like one before every commit.
- Never use
--no-verify to skip hooks without being explicitly told to.
- Never amend or force-push published history.
- Never write bodies that restate the diff line by line.
Done means
The working tree is clean or intentionally dirty, every commit passes git log --oneline readability (a stranger can follow the story), and tests pass on the final commit.
1---2name: conventional-commits3description: Use when committing changes to git. Analyzes the staged diff, splits unrelated changes into separate commits, and writes conventional commit messages that explain why, not just what.4---56# Conventional Commits78Produce commits a future maintainer can trust: atomic, well-scoped, and explained.910## Protocol11121. **Survey before staging.** Run `git status` and `git diff` (both staged and unstaged). Never commit blind.132. **Split unrelated work.** If the diff mixes concerns (a bugfix plus a refactor plus a config tweak), stage and commit them separately. One logical change per commit.143. **Choose the type** from: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`. When two apply, pick the one that matches the *intent* of the change, not its file types.154. **Write the subject line.**16 - Format: `type(scope): imperative summary` under 72 characters17 - Scope is the module or area touched, only when it adds clarity18 - Imperative mood: "add", "fix", "remove", never "added" or "adds"195. **Write the body only when the diff cannot speak for itself.** The body answers *why*: what problem existed, why this approach. Wrap at 72 characters.206. **Verify before committing.** If the repo has a test or lint command, run it on the staged state first.2122## Never2324- Never commit secrets, keys, `.env` files, or credentials. Check the diff for anything that looks like one before every commit.25- Never use `--no-verify` to skip hooks without being explicitly told to.26- Never amend or force-push published history.27- Never write bodies that restate the diff line by line.2829## Done means3031The working tree is clean or intentionally dirty, every commit passes `git log --oneline` readability (a stranger can follow the story), and tests pass on the final commit.
dkenge123-oss