Conventional Commits: the commit message as a technical document

Most teams have never explicitly discussed how to write commit messages. An unspoken convention forms over time, often shaped by the style of the first developer to open the repository, and that convention persists until the team grows and coherence quietly deteriorates. The commit message is the most pervasive historical document a project produces: every technical decision, every bug fix, every refactoring leaves a trace. Treating that trace as a free-form field to fill in however one likes means squandering one of the most valuable understanding tools available to anyone working on the code, today or years from now.

The structure of the format

Conventional Commits is a lightweight specification that defines a minimal set of rules for message structure. The format includes a type, an optional scope, and a short description, followed by an optional body and footers. The canonical types are few and immediately intuitive: feat for a new feature, fix for a bug correction, docs for documentation, refactor for reorganisations that do not change external behaviour, chore for maintenance tasks such as dependency updates. An exclamation mark after the type signals a breaking change, information that would otherwise require reading the full diff to identify.

# A new feature with a scope
feat(auth): add password strength meter

# A bug fix
fix(api): handle null response from payment gateway

# Documentation only
docs: update installation steps in README

# A breaking change, signalled by the exclamation mark
feat(api)!: drop support for legacy v1 endpoints

This structure is not arbitrary. It derives from the observation that commit messages serve to answer different questions depending on who reads them and when: a developer investigating a bug needs to know what changed and why, a technical lead preparing a release needs to understand what goes in the changelog and which semantic version to assign, a new team member needs to reconstruct the evolution of a piece of code without opening every individual diff. The format answers all these needs with the same structure.

The value of tooling

The most immediate and measurable benefit of adopting Conventional Commits is access to an ecosystem of tools that operate directly on message structure. Semantic-release analyses commits since the last tag, automatically determines the version type to release based on the conventions present (patch for fixes, minor for features, major for breaking changes), and publishes the release with the generated changelog. Google’s Release-please does the same for projects hosted on GitHub, automatically opening a release pull request whenever commits have accumulated on the main branch. Conventional-changelog produces readable documents in any format without requiring additional configuration.

These tools are not marginal advantages. They eliminate a category of repetitive, error-prone manual work: deciding which version to assign, writing the changelog, coordinating the release among team members. When the release process is determined by the structure of commits it is no longer a decision requiring a meeting or subjective judgement, but an automatic consequence of what the team has already documented in its normal workflow.

Readability as a project requirement

There is a less visible dimension of the value of Conventional Commits that concerns onboarding and long-term maintenance. A repository with a coherent, structured commit history is one in which a new developer can find their footing without having to ask anyone. Filtering commits by type, finding all fixes applied to a given module, reconstructing the history of a feature: operations that with free-form messages require reading and interpreting every entry become direct queries against structured metadata.

This has concrete consequences for how quickly a team can respond to an incident. When something breaks in production and the task is to identify which commit introduced the regression, the difference between a readable history and a list of messages like “fix”, “update”, “miscellaneous changes” can amount to hours of investigation. The structure does not serve the moment the commit is written, but every subsequent moment when that decision must be understood by someone who was not there.

Gradual adoption with commitlint

Adopting Conventional Commits in a team does not require a retroactive migration or significant upfront effort. The most widely used tool for enforcing the format is commitlint, configurable in a few minutes and integrable with Husky or Lefthook to run validation as a commit-msg hook. Any message that does not meet the structure is rejected immediately, before it reaches the remote repository, with an error message that indicates exactly what to correct.

The base configuration requires two packages and a minimal configuration file. Commitlint reads the message, validates it against the defined rules, and blocks the commit if the structure is not compliant. Adoption becomes gradual because every new commit written in the correct format moves the repository’s history toward coherence without touching existing commits. In teams using editors such as VS Code, extensions that suggest the format as you type further reduce the initial friction.

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
};

The best time to introduce Conventional Commits is at the start of a project, but the second-best time is now. A partially structured commit history is already more useful than a completely free-form one, and the tooling works correctly even on repositories that have non-compliant commits in the past because it only operates on the range since the last release tag. The investment required is minimal compared to the value it returns over time: fewer manual versioning decisions, automatically generated changelogs, and a project history that answers questions instead of multiplying them.

The full specification, with all the format rules and examples, is available on the official Conventional Commits website.