Commit message

Commit Messages

Generate paste-ready commit messages using the Conventional Commits standard. Optimize for a clean project history: one logical change, clear type, useful scope, imperative subject, and body/footer only when they add information the subject cannot carry.

Format

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Rules:

• Use lowercase type.
• Use an optional lowercase scope in parentheses: fix(checkout): ....
• Use ! only for breaking changes: feat(api)!: change pagination contract.
• Keep the subject under 50 characters; 72 is the hard maximum.
• Use imperative mood: add, fix, remove, update; not added, fixed, updates.
• Do not end the subject with a period.

Types

Type	Use for
feat	New user-visible, API-visible, or product behavior
fix	Bug fix or correction to broken behavior
perf	Performance improvement without behavior change
refactor	Code restructuring that is not a fix or feature
test	Adding or correcting tests only
docs	Documentation-only changes
style	Formatting, whitespace, lint-only, no logic change
build	Build system, packaging, lockfiles, Docker build changes
ci	CI/CD pipeline or automation changes
chore	Maintenance that does not fit another type
revert	Reverting a previous commit

Type selection:

• Prefer feat only when behavior is added for a user, API consumer, or operator.
• Prefer fix when the change corrects a defect, even if tests or refactors are included.
• Prefer perf only when the main point is measurable performance.
• Prefer build for dependency manifests or build tooling; use chore(deps) only if that is the project's convention.
• If multiple unrelated changes are present, recommend splitting commits instead of hiding them behind one vague message.

Scope

Use the smallest meaningful area affected by the change. Derive scope from package, service, feature, route, module, app, or domain name. Omit scope when no useful scope is obvious.

Common examples:

• Backend: auth, users, orders, payments, mailer, queue, db, config, api
• Frontend: ui, layout, checkout, cart, forms, routing, hooks, styles
• Mobile: navigation, screens, offline, push, storage, api
• Magento: checkout, catalog, customer, order, payment, theme, module
• Tooling: deps, ci, docker, lint, release

Do not invent a noisy scope if the change is repository-wide.

Workflow

Step 1: Understand The Change

Use the user's diff, status, or description. Identify:

• What behavior changed
• Why it changed
• The dominant affected area
• Whether it is breaking
• Whether the changes should be split

If context is missing but the user clearly wants a commit message, make the best message from the provided description and avoid interrogating them. Ask a question only when the type would be dangerously misleading.

Step 2: Detect Split Commits

Recommend splitting when the change includes unrelated logical units, for example:

• Feature plus formatting across unrelated files
• Dependency upgrade plus business logic change
• Refactor plus unrelated bug fix
• Generated files mixed with manual behavior changes

Output split suggestions as separate commit messages. If the user asks for a single commit anyway, use the dominant change and mention the compromise briefly outside the code block.

Step 3: Choose Type, Scope, And Breaking Marker

Use ! and a BREAKING CHANGE: footer when the commit changes an API, schema, config contract, CLI behavior, data format, auth behavior, migration requirement, or other consumer-facing contract.

Breaking example:

feat(api)!: replace page pagination with cursors

BREAKING CHANGE: The orders endpoint no longer accepts page and
limit query params. Clients must use cursor and take instead.

Step 4: Write The Subject

Pattern:

<type>(<scope>): <imperative description>

Good subjects:

feat(auth): add refresh token rotation
fix(checkout): prevent duplicate order submission
refactor(users): extract email validation helper
perf(catalog): cache product listing queries
build(deps): update class-validator

Bad subjects:

fix bug
updated auth
feat: added some improvements
WIP
changes

Step 5: Add Body Or Footer Only When Useful

Add a body when it explains non-obvious why, migration notes, operational impact, or risk. Do not restate the diff.

Useful body:

fix(payments): make gateway retries idempotent

The gateway can time out while still processing the charge. Reusing
the order attempt id as the idempotency key prevents duplicate charges
when the retry succeeds after the original request.

Footers:

• BREAKING CHANGE: ... for breaking changes
• Refs: #123, Closes: #123, or project-specific issue references only when provided

Output Format

Default: return only the commit message in a fenced code block.

fix(checkout): prevent duplicate order submission

If multiple commits are recommended, return a short heading and one fenced block per commit:

Suggested split:

fix(checkout): prevent duplicate order submission

test(checkout): add duplicate submission coverage

If you need to explain a tradeoff, keep the explanation outside the code block and under two sentences.

Quality Bar

• Paste-ready output, no extra decoration.
• One logical change per commit whenever possible.
• Subject is specific enough to understand in git log --oneline.
• Body explains why, not what, when a body is needed.
• Breaking changes are marked with both ! and BREAKING CHANGE:.
• Do not fabricate ticket numbers, scopes, migration notes, or breaking impact.