Semantic Commit Messages

semantic-commit-messages.md

Semantic Commit Messages

See how a minor change to your commit message style can make you a better programmer.

Format: <type>(<scope>): <subject>

<scope> is optional

Example

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

More Examples:

• feat: (new feature for the user, not a new feature for build script)
• fix: (bug fix for the user, not a fix to a build script)
• docs: (changes to the documentation)
• style: (formatting, missing semi colons, etc; no production code change)
• refactor: (refactoring production code, eg. renaming a variable)
• test: (adding missing tests, refactoring tests; no production code change)
• chore: (updating grunt tasks etc; no production code change)

References:

• https://www.conventionalcommits.org/
• https://seesparkbox.com/foundry/semantic_commit_messages
• http://karma-runner.github.io/1.0/dev/git-commit-msg.html

this is an unnecessarily complex "protocol", most of the keywords have no bearing on semver and are just noise.

Thanks! Now I know who to blame for having to use this absolutely pointless and brain-damage-inducing spec.

@nicholaswmin @Alluseri Conventional Commits do introduce some rules, which might add a bit of overhead.

However, in my humble opinion, they make commit history much more organized—especially in larger projects with multiple contributors. The structure improves readability, maintainability, and even enables automation (like changelog generation).

Since Conventional Commits is still in its early stages, it may evolve to become simpler and more intuitive over time. If people have concerns, they could contribute to the project to help shape its future—rather than just criticizing it. Of course, if it doesn’t suit their workflow, they’re free not to use it. 😉

@cfgnunes I agree with most.

they could contribute to the project to help shape its future—rather than just criticizing it.

My contribution is my feedback - I don't have a moral obligation to fix everything I believe is broken.

The structure improves readability, maintainability, and even enables automation (like change log generation).

I very much agree with the philosophy of the project but i'm very against the idea of having so many keywords. I literally have to look up the appropriate keyword.
And this isn't some critical functionality, it's the just...changelog management.

There is no need to have so many keywords for the vast majority of projects.
There is an ongoing trend since the late 00's to cargo-cult secondary helper bolt-ons to projects, such as this this (then husky then this thin that) that do nothing other than scare juniors off from contributing and/or add unnecessary dependencies and mental noise. This has a name and it's a terrible engineering decision.

Is your project SemVered? Yes? Then you've added another process but it can be justified by the fact it now helps you automate SemVer compliance. Ok fair tradeoff.
Do you need that many keywords to figure that out automatically? No.
Please pay attention to your own contexts instead of jumping onto bandwagons. Process is bad. Don't introduce it unnecessarily or prematurely. If there is one adage that survives every bit of scrutiny without fail its KISS

That being said, I appreciate the reply man. And the authors of CC - the fact I disagree with a part of it doesn't mean anything nore than that.

@nicholaswmin Great points!

I agree that simplicity is essential, and processes shouldn’t be added without a good reason. While Conventional Commits offers a broad set of keywords to provide flexibility, it's worth considering whether a smaller, more essential subset could cover most cases without unnecessary overhead.

That said, it's important to recognize that Semantic Commit, as it stands today, may not be useful for all types of projects. There’s no silver bullet in software engineering—it’s up to each team to evaluate what truly adds value to their workflow. Dismissing the project as "cargo cult programming" might be unfair; we risk misjudging its real purpose or, worse, falling into a Dunning-Kruger effect, where a lack of deeper understanding leads to oversimplified conclusions.

I believe discussions like these are valuable for refining tools, but at the same time, sometimes debates about tooling create more noise than the tools themselves—lots of talk, little action. Personally, I prefer to focus on building rather than overanalyzing.

Thanks for the exchange of ideas!

Ok to make this clear:

• CC is good
• The keywords must be drastically reduced

"Dismissing the project as cargo cult programming"

I'm not dismissing the project itself as cargo cult programming; that doesn't make sense.
I'm dismissing the overzealous adoption of unnecessary procecess/tools/conventions prematurely, for no concrete reason other than "I also do that"

Curious what people do when more than one type of "thing" is done in a single commit. For instance, to polish up some python code before committing I ran RightTyper, Trunk format, and then added in some comments on the code.

"Learn to commit between each task" is good advice but sometimes that horse is already out of the barn.

nice script @cfgnunes; but you can also use pre-commit hook to enforce it.