conventional-commits
Proposal: Clearer definitions for Conventional Commit types
We conducted a study and found that conventional commits are becoming increasingly popular among top open-source projects. Specifically, there is a stable uptrend in the adoption of conventional commits, with some projects mandating their use. By 2023, in repositories that do not require conventional commits, we found nearly 10% of commits were in line with the Conventional Commit format, indicating their popularity among developers.
During this process, we noticed that some commits, despite being conventional, clearly misused the commit message format, for example: feat: remove unnecessary lines from test file. This spurred our curiosity about the challenges developers face when categorizing commits using the conventional commits format. Therefore, we analyzed all the issues in this project, as well as the top 100 questions on Stack Overflow related to conventional commits. Our analysis identified four categories of challenges developers face, with the most common (around 57.7%) being confusion over which type to use. In the current CCS definition, categories other than 'feat' and 'fix' lack clear definitions, leading developers to rely on the categorizations used by Angular and other projects, which often overlap and lack clarity. For instance, in Angular's definition, 'refactor' is defined as "A code change that neither fixes a bug nor adds a feature," which could ambiguously include 'style', 'perf', 'test', among others.
We have proposed a clearer and less overlapping list of definitions based on our literature review and the documentation in repositories currently using conventional commits. Based on this, we have drafted an academic paper (you can find more detailed information about the above here), which has undergone peer review and been accepted by ICSE 2025, a premier software engineering conference.
We are happy to provide additional details or clarification about our methodology and findings. We look forward to any feedback you may have.
@0x404 this is super interesting. Apologies that I'm a terrible open source maintainer these days, and am responding months after the fact.
If you would like to draft a recommendation for a better set of recommended types, I'm very open to the discussion. As long as we maintain the goal of simplicity and minimalism.
Personally, I think less is more in terms of categories, preferring to almost always use feat:, fix:, docs:, fix(deps): (for a dependency update).
Hi @bcoe, my sincere apologies for the late update, just been through an exceptionally busy month.
I would absolutely love to draft a definition list for conventional commit types. Below are the definitions we proposed in our paper:
- feat: Code changes aim to introduce new features to the codebase, encompassing both internal and user-oriented features.
- fix: Code changes aim to fix bugs and faults within the codebase.
- perf: Code changes aim to improve performance, such as enhancing execution speed or reducing memory consumption.
- style: Code changes aim to improve readability without affecting the meaning of the code. This type encompasses aspects like variable naming, indentation, and addressing linting or code analysis warnings.
- refactor: Code changes aim to restructure the program without changing its functional behavior, aiming to improve maintainability. (To avoid confusion and overlap, we propose the constraint that this category does not include changes classified as "perf" or "style") Examples include enhancing modularity, refining exception handling, improving scalability, conducting code cleanup, and removing deprecated code.
- docs: Code changes that modify documentation or text, such as correcting typos, modifying comments, or updating documentation.
- test: Code changes that modify test files, including the addition or updating of tests.
- ci: Code changes to CI (Continuous Integration) configuration files and scripts, such as configuring or updating CI/CD scripts, e.g.,
.travis.yml'' and.github/workflows''. - build: Code changes affecting the build system (e.g., Maven, Gradle, Cargo). Change examples include updating dependencies, configuring build configurations, and adding scripts.
- chore: Code changes for other miscellaneous tasks that do not neatly fit into any of the above categories.
I completely agree that less is more when it comes to categories, but I believe having clear definitions helps users understand each type better. The current Conventional Commits 1.0 specification redirects to projects like Angular, but Angular's definitions are quite ambiguous with overlap. For example, their "refactor" definition ("A code change that neither fixes a bug nor adds a feature") is problematic.
I think we could streamline these proposed definitions while maintaining clarity to help users better understand each type. I'd greatly appreciate any insights you might have, and I'm available to collaborate on this, I'll respond as promptly as possible.
As it's used to say, a picture is worth a thousand words... 😄
This diagram represents the orthogonal relation between source code categories (black boxes, upper-left labels) and Conventional Commits types (colored boxes, lower-right labels).
Related commit types share the same color:
- refactoring-related commit types are marked in yellow
- configuration-related commit types are marked in orange
EDITS:
- API code subset has been expanded to encompass API fixes
- BREAKING CHANGE commit subset has been expanded to encompass all possible cases
