Conventional Commits

Conventional commits provide a standardized format for commit messages that communicates the type and scope of changes systematically. This convention enables automation for versioning, changelog generation, and release management. Design systems benefit particularly from conventional commits due to their emphasis on clear communication with consumers.

What Are Conventional Commits

Conventional commits follow a structured format that encodes information about each change. The basic format includes a type, optional scope, and description: type(scope): description. Types like feat, fix, and docs indicate the nature of changes. Scopes identify the affected component or area.

The convention originated from the Angular project and has been widely adopted across the JavaScript ecosystem. It provides a lightweight specification that humans can write and machines can parse. This dual readability makes conventional commits valuable for both communication and automation.

How Conventional Commits Work

Conventional commit messages follow a specific structure that conveys change information consistently. The structure enables both human understanding and automated processing.

The type prefix indicates the category of change. Common types include feat for new features, fix for bug fixes, docs for documentation changes, style for formatting, refactor for code restructuring, test for test additions, and chore for maintenance tasks. The type maps to semantic version increments and changelog sections.

The optional scope narrows the change context. In design systems, scopes often identify components like button, modal, or tokens. Scopes help consumers understand which parts of the design system are affected without reading the full change description.

The description explains the change concisely. It should complete the sentence “this commit will…” using imperative mood. Good descriptions focus on what changed and why rather than how the implementation works.

Breaking changes receive special treatment. Including BREAKING CHANGE in the commit footer or adding an exclamation mark after the type signals incompatible changes. These markers trigger major version increments in automated versioning systems.

Key Considerations

• Enforce conventions through commit hooks or CI validation
• Train team members on the convention and its benefits
• Types should map clearly to versioning and changelog categories
• Breaking change markers must be used consistently
• Scopes should align with how consumers think about the design system

Common Questions

How do conventional commits integrate with semantic versioning?

Conventional commits provide the information needed to determine semantic version increments automatically. Commit types map to version segments following defined rules.

Fix commits trigger patch version increments (1.0.0 to 1.0.1). They represent backwards-compatible bug fixes. Feat commits trigger minor version increments (1.0.0 to 1.1.0). They represent backwards-compatible feature additions. Breaking change markers trigger major version increments (1.0.0 to 2.0.0).

Tools like semantic-release and standard-version analyze commits since the last release, identify the highest-impact change type, and increment the version accordingly. This automation eliminates manual version decision-making and ensures version numbers accurately reflect changes.

What enforcement mechanisms work for conventional commits?

Several tools help enforce conventional commit formatting. Commitlint validates commit messages against the conventional commits specification, running during git commit hooks or CI pipelines. Husky manages git hooks, triggering commitlint and other validations.

Commitizen provides interactive commit message creation, prompting developers for type, scope, and description. This approach helps developers unfamiliar with the convention write valid messages. It can be configured to match specific project conventions.

Pull request validation can check that all commits or the squash commit message follow conventions. GitHub Actions, GitLab CI, and other CI systems can run commitlint against pull request commits.

Summary

Conventional commits standardize commit message formatting to enable automation and improve communication. The structured format including type, scope, and description provides information for versioning and changelog generation. Enforcement through hooks and CI ensures consistent adoption across teams.