Conventional Commit Writer

Write a commit message that follows the Conventional Commits 1.0.0 spec, so history is readable and tools can derive versions and changelogs automatically.

Format

<type>(<optional scope>): <subject>
<BLANK LINE>
<optional body — what and why, not how>
<BLANK LINE>
<optional footer(s) — BREAKING CHANGE, Refs, Closes>

Step 1 — Inspect the change

If you have repo access, base the message on the actual diff, not assumptions:

Staged changes: !`git diff --cached --stat`

If the diff is empty, note there are no staged changes and ask what was changed (or read the unstaged diff).

Step 2 — Pick the type

Pick the single most important type. If a change is both a feature and a fix, prefer feat and describe the fix in the body.

Step 3 — Scope (optional but useful)

A noun in parentheses naming the affected area: feat(auth):, fix(api):, docs(readme):. Keep scopes from a small, consistent set. Omit the scope rather than inventing a vague one.

Step 4 — Write the subject

• Imperative mood: "add", "fix", "remove" — not "added", "fixes", "adding".
• No capital first letter after the colon, no trailing period.
• Aim for ≤50 characters; hard cap 72.
• Complete the sentence: "If applied, this commit will <subject>."

Step 5 — Body and footers (when warranted)

Add a body when the why isn't obvious from the subject. Wrap at ~72 columns. Explain the motivation and contrast with previous behavior; the code already shows the how.

Footers reference issues and declare breaking changes:

Closes #123
Refs #456
Reviewed-by: Jane Doe

Step 6 — Breaking changes

Two equivalent ways to mark a breaking change; use the footer for tooling and the ! for visibility:

feat(api)!: drop support for legacy v1 auth tokens

BREAKING CHANGE: v1 bearer tokens are no longer accepted. Clients must
migrate to OAuth2 access tokens. See MIGRATION.md.

A BREAKING CHANGE: footer (or !) signals a MAJOR version bump regardless of type.

Examples

Input: Added a /healthz endpoint that returns 200 when the DB is reachable. Output:

feat(api): add /healthz readiness endpoint

Returns 200 when the database connection is live, 503 otherwise, so the
load balancer can route around unhealthy instances.

Input: Fixed dates rendering one day off due to timezone handling. Output:

fix(reports): use UTC to prevent off-by-one dates

Report timestamps were formatted in local time, shifting dates across the
midnight boundary. Format consistently in UTC.

Closes #842

Input: Bumped lodash and removed an unused helper. Output:

chore(deps): upgrade lodash to 4.17.21 and drop unused util

- Patches a prototype-pollution advisory
- Removes the now-unreferenced deepClone helper

Common edge cases

• Mixed unrelated changes: recommend splitting into separate commits; if that's not possible, lead with the most significant type and enumerate the rest in the body.
• Revert: revert: <subject of reverted commit> with a body This reverts commit <sha>.
• WIP/merge commits: Conventional Commits is for meaningful history; squash WIP commits before merging.
• No issue tracker: omit footers rather than inventing references.