Conventional Commits: Why a Focus on Type Over Scope is a Technical Anti-Pattern
Conventional Commits is a widely adopted standard for structuring commit messages, but it fundamentally prioritizes the wrong metadata. By placing the commit type (e.g., fix, feat) before the scope (the area of the code being changed), the standard fails to provide the most critical information to the people who actually read commit logs: contributors, debuggers, and incident responders.
The Failure of Type-First Prioritization
Conventional Commits mandates a format where the type is required and the scope is optional. This is a technical failure because the scope—the subject of the change—is the most important piece of information for navigating a codebase.
Why Scope Outweighs Type
For most technical stakeholders, the area of the code touched is more valuable than the category of the change:
- Contributors: Need to identify changes in specific areas of the codebase to understand project inertia or identify potential merge conflicts.
- Debuggers: Search for changes in components related to a manifested bug; the type of change is irrelevant because bugs can be introduced by any commit type.
- Incident Responders: Scan logs during production outages to find changes in specific subsystems (e.g.,
auth) that correlate with the spike in errors.
The Redundancy of Commit Types
Commit types are often redundant because a well-written description typically implies the type. For example, a commit titled fix(compiler): prevent namespaced SVG <style> elements from being stripped makes it obvious that it is a bugfix without the fix: prefix. Furthermore, the rigid categories of Conventional Commits can be restrictive, as many changes are simultaneously a refactor, a bugfix, and a feature.
The Illusion of Automated Benefits
Conventional Commits promises several automation benefits that often fail in real-world software engineering scenarios.
Automated Changelogs
Automated changelogs conflate two different audiences: the developer (who reads the commit log to see how the codebase evolved) and the end-user (who reads a changelog to understand functional business changes). A single feature often requires multiple commits; presenting a raw list of these commits to a user is suboptimal. Additionally, reverts are problematic, as a reverted change should typically be invisible to an end-user but is vital for a developer's history.
Automated Semantic Versioning (SemVer)
Using commit types to trigger version bumps (e.g., feat! for a major version) is unreliable due to several factors:
- Reverts: A breaking change that is immediately reverted may still trigger a major version bump in automated tooling.
- Accidental Breakages: Subtle breaking changes may not be identified at the time of commit, leading to an incorrect minor/patch version bump.
- Retroactive Fixes: Subsequent commits may resolve a breaking change before a release, yet the tooling still sees the initial breaking commit.
Automated Build and Publish Triggers
Triggering security checks or builds based on commit types (e.g., skipping checks for docs:) is a security risk. A malicious actor could label a commit as docs: while introducing a vulnerability into the authentication subsystem, bypassing automated tooling.
A Proven Alternative: Scope-Prefixed Commits
Many of the most successful open-source projects—including the Linux kernel, Git, Go, and FreeBSD—reject the Conventional Commits standard in favor of scope-prefixed messages. In these projects, the scope is the primary identifier, and the type is either implicit or omitted.
| Project | Format | Example |
|---|---|---|
| Linux | subsystem: description |
i2c: virtio: mark device ready before registering the adapter |
| Go | package: description |
net/http/cookiejar: add godoc links |
| Git | area: description |
gitlab-ci: update macOS image |
| FreeBSD | prefix: description |
linuxulator: Return EINVAL for invalid inotify flags |
Community Perspectives and Counterpoints
While the critique of Conventional Commits is sharp, community discussion highlights several reasons why the standard persists:
- Enforcement and Quality Control: Some maintainers argue that enforcing a schema via pre-commit hooks is the only way to prevent "horrendous" commit messages from inexperienced developers.
- Continuous Delivery (CD): For smaller projects or those with aggressive CD pipelines, the ability to automatically tag and ship versions based on commit types is a significant operational advantage.
- The "Good Enough" Standard: Some developers argue that while not optimal, having a defined structure is better than having no structure at all, comparing it to the adoption of JSON despite its lack of comments.
Ultimately, the debate centers on whether the commit message should serve as a machine-readable trigger for automation or a human-readable record of architectural evolution. The evidence from large-scale, long-lived projects suggests that prioritizing scope and human clarity over automated types is the more sustainable approach.