Conventional Commits

Conventional Commits is a convention for writing commit messages in a machine-readable form: a type, an optional scope, and a short description — `fix(auth): reject expired refresh tokens` — with an optional body and footer for breaking changes and issue references. The value is not tidiness for its own sake. Once messages carry a type, tooling can generate a changelog, decide the next semantic version, and route a release without anyone maintaining that information by hand. The mapping is the reason the convention spread: a fix implies a patch release, a feature implies a minor one, and a breaking-change marker implies a major one, so version numbers stop being a judgement call made at release time. It also makes history greppable — filtering a year of commits to the ones that changed behaviour rather than formatting is a genuinely useful operation during an incident. Two caveats keep it from becoming ritual. A convention enforced by a commit-message linter but not by review produces correctly-formatted messages that describe nothing; `fix(api): fix bug` satisfies the rule and helps no one, and the description is the part that matters most six months later. And the type must reflect what the change does to consumers, not how the author feels about it — a refactor that alters an API response is a breaking change however internal it felt. Teams squashing pull requests should note that the squash message is the one that reaches history, so that is where the convention has to hold.