Introduction
If you're involved in software development, chances are you've encountered the concept of Conventional Commits. This method, widely adopted in open-source projects, proposes a standardized structure for commit messages, supposedly adding clear semantics and aiding in understanding changes. However, in practice, this standard often proves ineffective and counterproductive.
The Unfulfilled Promises of Conventional Commits
Conventional Commits aim to add value by making commit logs easier to read. The idea is to structure each message according to a precise format: <type>[optional scope]: <description> [optional body] [optional footer(s)]. But this format emphasizes the type of change rather than its scope, which is nonsensical.
Take an example: in a complex project, a commit marked as feat doesn't say much about the real impact of the change. Conversely, the scope field, which could detail the affected code area, is often relegated to the background. In critical situations like bug fixing or incident responses, these scope details are precisely what matter most.
A More Pragmatic Approach
Importance of Scope
The importance of scope becomes evident when considering the needs of different project stakeholders:
- Contributors: They need to quickly understand which parts of the code have been modified to ensure compatibility with their own work.
- Debuggers: When a bug occurs, quickly identifying changes in the affected code area helps target investigations.
- Incident Responders: In case of a breakdown, it's crucial to efficiently scan logs to spot recent changes in the affected area.
A Concrete Use Case
Imagine a project developing a SaaS application. The commit log is used to track changes and understand the evolution of the code. If commit messages are too general (e.g., only fix or refactor), it becomes hard for new developers to navigate. On the other hand, focusing on scope (auth-module: fix token refresh bug) immediately clarifies the impact of the change.
Alternatives to Conventional Commits
Scoped Commits
Rather than focusing on the type, a more effective method could be structuring commits around their scope. This means each commit message should start with a clear indication of the affected code area, followed by a succinct description of the change.
Integration of Automation Tools
Modern tools like GitHub Actions or GitLab CI/CD can be configured to automatically analyze commit messages and generate more useful reports tailored to team needs.
Conclusion
Conventional Commits, although adopted by many projects, do not deliver on their promises of clarity and efficiency. By reconsidering the approach to emphasize the scope of changes, you can improve the readability of commit logs and help your team become more efficient.
Let's discuss your project in 15 minutes.