Make the subject a verifiable summary
A commit message is a small record attached to a change. It helps a later reader understand why the commit exists without reconstructing the whole discussion. Start by reviewing the actual patch, then describe the change that is present. Avoid claiming an outcome that was not tested or an intention that was never part of the decision.
Conventional Commits provides a structured message form built around a type, an optional scope, a description, and optional body or footers. Its specification associates types such as feat and fix with kinds of change and defines a breaking-change marker and footer convention. A project may adapt the format, so read its contribution guide before applying a template. Formatting consistency is useful only when the content remains accurate.
Choose a type from the change, not the team's wish
Use a type that describes the patch. A feature type signals added capability; a fix type describes a correction. Documentation, tests, refactoring, build work, and maintenance can use project-approved categories. If a change spans multiple purposes, split it when that improves review or history. If it cannot be split, choose the type that best describes the primary change and explain the rest in the body.
The scope should narrow the subject to a component or area that readers recognize. It is a label, not a substitute for the summary. Prefer a concise phrase such as parser or settings over a vague phrase such as update. Do not invent an issue number, release version, team name, or affected customer if the repository does not establish it.
Describe the action and the useful object
A strong subject names what changed in terms a future maintainer can search for. “Preserve repeated query keys” says more than “Update parser.” “Explain missing configuration” is more useful than “Improve error.” Keep the subject short enough to scan, but do not remove the object that makes the change intelligible.
Use a verb form and capitalization rule that matches the project. Conventional Commits defines a syntax; teams may add style rules. The Benchlight Commit Message Composer validates a small set of type names, assembles a scope and summary, and places a breaking-change note when requested. It reports subject length and warns above 72 characters. That suggestion does not establish a project policy; the tool does not inspect Git, verify the patch, or decide whether the type is correct.
Use the body for the reason and constraints
The body can explain why the change was needed, what trade-off was chosen, and what a reviewer should know. It can capture a constraint that is not obvious from the code. Keep it concrete: describe the prior behavior, the new behavior, and the reason for the transition. If evidence is uncertain, state that uncertainty instead of presenting an assumption as fact.
Avoid repeating the subject in different words. Do not use the body as a pasted diff, a retrospective essay, or an unsupported claim that a bug is permanently solved. If tests were run, report the actual command and outcome in the project’s preferred location. A commit message can point to an issue or design record only when that reference is real and accessible to the intended maintainers.
Record breaking changes explicitly
A breaking change alters a contract that a consumer may depend on. It could involve a public API, a command-line option, a file format, configuration, or documented behavior. The marker alone is not migration guidance. Explain what changed, who may be affected, and how a consumer should adapt when those facts are known.
Before labeling a change as breaking, check the supported compatibility promise and actual consumers. A private refactor that changes internal structure may not affect users; a seemingly small default change may. If impact is unknown, investigate before writing a definitive footer. The composer requires a note when the breaking option is selected, but it cannot determine whether the choice is justified.
Make messages match the commit boundary
One commit should usually tell one coherent story. If a commit combines an unrelated dependency bump, a formatting sweep, and a behavioral fix, a reader may struggle to understand or revert it. Consider splitting the work so each message describes a reviewable unit. Do not create an artificial split that makes intermediate commits fail or removes the context needed to understand the change.
Check that the staged patch matches the subject. A message about one bug should not accompany unrelated changes. Review the final diff and tests before committing, especially after staging only part of a file. The message is a claim about the commit object, so verify the object it will describe.
Assemble a message for an explicit compatibility change
Consider a fictional command-line project that has deliberately replaced its required config option with settings. In Commit Message Composer choose feat, scope cli, breaking Yes, and summary require settings option. Supply a body explaining the change and a breaking note instructing users to replace --config with --settings. The resulting structure is:
feat(cli)!: require settings option
Read the startup file from the settings option.
BREAKING CHANGE: replace --config with --settings in startup commands.
The exclamation mark and footer describe the same compatibility event. Conventional Commits permits the exclamation mark without a footer, but this composer deliberately requires the extra note when its breaking option is selected. That is a product rule intended to request migration detail, not an additional requirement of the specification. A project that follows another convention should apply its own contribution rules.
Before using this draft in a real repository, check whether the old option truly stopped working. If it remains as a supported alias, the fictional breaking description would misrepresent the patch. If only an internal variable was renamed, a cli compatibility warning would also be misleading. The meaningful review compares the public invocation before and after the change, including the documented support window.
The composer reports the full subject length, including the type and scope, and warns above 72 characters. It does not reject a longer subject or establish the repository's preferred length. If a long message triggers the warning, shorten redundant wording while retaining the affected operation. Do not remove a necessary migration fact to achieve an arbitrary count.
This message serves maintainers examining one commit. A release note for the same fictional change would instead explain which users need to edit their startup command and in which shipped version. That difference in audience is why the commit-message guide and release-notes guide remain separate articles.