As programmers I feel like we'll always nitpick and bitch over what the optimal setup is for rather mundane things (tabs v spaces, yada yada).
I'm not saying that conventional commits are God's given best way to structure a commit message, but they are a defined structure, and I find it much more effective and important that some expectations be set around commit messages, and I think conventional commits are as good as anything.
Like the author is making a big deal that they think scope is more important than type. I may tend to agree, but I think the difference between "fix(compiler)" and "compiler fix" is not exactly a hill I'd be willing to die on.
The tech industry has tons of things that became standards even if they weren't optimal. E.g. if one were starting from scratch I think any sane person would argue JSON should support comments (sorry but Douglas Crawford's rationale for not including comments never made sense to me), better defined numeric formats, etc. But it was better in many contexts than what came before it, so it became the standard. I could believe that there is some other format that differs a bit from conventional commits that is a little better, but not really better enough to want a whole other competing way of structuring comments.
The real takeaway is that different projects have different requirements.
In over 30 years of using source control, I've never once worked on something where it's useful to include the component (article calls it scope) in the description in a standardised way. It's obvious what components are affected based on where in the source tree the affected files are. Similarly "bug", "fix" or "feature" adds no useful value. It's important or it wouldn't be checked in.
The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all the information about what was done in the change, what's missing is the context about why.
Even on my solo projects I include a JIRA reference in square brackets before the description. If it's just something I randomly decided to fix during the course of development, I'll create a short 1 line JIRA to get an id and explain the why there.
It is useful if you automate generating release notes. Then your notes are grouped by new features first, then bug fixes after. This makes it a little easier for non-technical uses to read.
My main complaint with conventional commits always was that they don't include an issue number in the commit title. It's not even mentioned in their standards as optional or something.
To me this is almost the most important information in a commit message. I don't know how often in the last 15 years I was cross checking the issue description referenced by some old commit to get the full context of a change. I also felt that this habit is kind of standard - until i had to learn about "conventional commits".
I personally prefer including issues as git trailers:
fix thing in foo
Issue: ABC-123
Git has plenty of builtins for parsing and formatting these trailers, so you can easily create custom git log aliases that let you see them inline and parse them for use with CI.
Personally, if I am skimming a change log that is already limited in characters, I don’t care about ‘XYZ-999999’ in the main commit message. It’s good to tag as a trailer but I’d much rather see what the commit did than the Jira issue it came from.
It's totally fine to put the issue number somewhere at the end of the commit message, and not in line 1.
Most tools cross-link them as long as #<issue-id> is mentioned anywhere in the message. It's also useful the other way around, open an issue and see all associated commits.
Yeah the ticket value falls off pretty quickly to me. If I pull that up and it's been a closed issue for years and code has been added, rewritten, people moved, and tons of other changes to where the ticket is just a historical artifact and doesn't need priority in the first line of the commit message.
IMO that is only a problem for those who demand that the issue key needs to go first in the subject (which again IMO is bad for readability). I don't see why you can't just stick it somewhere after all the conventional commits junk? Issue keys ought to be something that can be janked out based on a regex like an alphanumeric prefix followed by a number, so things like this "standard" have little need to set aside a space for it.
Personally (without conventional commits) I tend to put them at the end in parentheses if the commit has something to do with that issue. But if there is a stronger relationship like that it fixes the issue, I put a `Fixes` trailer in the message as well.
Interesting, I guess we've been doing it wrong this whole time, as we do `fix(ABC-123): some message here`, which ends up being linked great, renders very nicely into the automated release notes, etc.
yeah this is the actual key. an actually useful title and a stable link to the discussion around the change.
conventional commits are pleasing, but questionable actual utility. the code speaks for itself. the actually useful information is a well chosen title and the context for the change.
Why do you even want the issue number in the commit title? I find that super annoying and unfortunately GitHub kind of forces it on you if you use merge queues.
It’s very helpful to know the motivation for the commit and if that motivation was tied to a client contract/feature. Especially in cases where a commit affects multiple files or even just one file so that all commits can be grouped into a feature/contract.
COMPANY-1234 in the title doesn't tell the reader all that much about the the feature or motivation. It does tell the client, but I'm not seeing why that is better than having it in the description as a tag, or some other nice way of extracting it.
Least of all when that ticket is older and so much of the code and the company has changed too. Like sometimes useful historical context sure but worth putting in the first line of a commit? I put it in the body with a link to the ticket or tickets as a footer, if someone wants historical context it's there.
The use of the word "chore" in many users of conventional commits has always riled me. I've always tended to favour the "linux kernel"[0] style of commit subject, which thankfully gets a mention here.
Completely agree, the attitude implied by “chore” is very off-putting to me. As if the rest should all be marked “fun” or “indifferent”. That kind of emotional judgement doesn’t belong in a commit message.
I’ve never personally used the chore term, but it doesn’t bother me to see it and I don’t feel it has a negative connotation.
Cleaning my kitchen after a meal may be a chore, but it’s not an intrinsically bad or unpleasant experience most of the time, it’s just good hygiene and afterwards I have the satisfaction of things being clean. Not cleaning the kitchen feels way worse to me as it ultimately leads to other far more unpleasant situations.
Such it is with updating dependencies, it generally needs to be done, so it’s good to do it, but it’s in no way noteworthy, so chore describes it perfectly, to me it signals that: “it’s work that needed to be done, but not for a feature, functionality change or bug fix on this particular code base, so you’re unlikely to see much change”.
It is bad terminology, yes. But also - a pretense that you know the overarching influence of a commit ahead of time, which you don't - but once you have conventional commits everyone on the team and the LLMs have to spend time/tokens inventing that stupid nomenclature.
Odd. The main reason to use this style of commit message is for CI/CD automation.
EDIT: I didn't see this covered in the article on my first pass. It is covered though. My apologies.
The type of the commit informs the automated workflows how to handle the commit. This is why it comes first.
For example, if you're performing CD, if you only commit a bunch of `fix: ` then only your semantic versioning patch version number is incremented. If you commit a `feat: ` then it's a minor version is bump. `feat! ` is a major version bump.
Even if you're not using CD for releases, semantic commit messages are sometimes used to automate change log generation. Granted, your change logs should not typically include the Git commit messages themselves — those are developer facing, not user facing.
The article addresses both of these pretty clearly. Semantic versioning gets borked with reverts and the automatic changelog is targeting the wrong audience
The article is wrong about reverts (in my opinion). If a breaking change is introduced, and then removed, the removal should also most likely be considered a breaking change (both the addition and removal are changing your API). So it is correct that a major version bump should occur when reverting. Once a package has been published, the ship has sailed.
The issue is that if there was no release in between, or only a beta or similar, you now have two breaking changes indicated by the commits, although in sum there is none since the last official release.
That's true, but depends on your workflow and release strategy.
If you are releasing upon every push to main/master (following what semantic release and conventional commits provides you in terms of automation), then it makes sense to perform major version bumps for the reverts.
If you have a manual release strategy, then it might not make sense to use these tools in the way they have been designed.
If you have actual dependents in a SemVer fashion, then this isn’t useful for those still on the prior version. What you’d rather do is decrement the major version again because it’s compatible with the prior version again. Those dependents who already upgraded to the interim version have to consider another breaking change regardless.
And if you don’t have these kinds of dependents, then the versioning scheme isn’t important anyway.
release-please[0] allows you to do a manual version override in a commit, which would allow you to decrement the major version upon reverting a breaking change
I think that could be simplified, so the tool can tell that a commit is reverting a breaking change and thus the version should be decremented, but at least there's an escape hatch.
My apologies, I missed this on first read due to the indentation style. That said, I don't agree on the commentary.
Why on Earth are people not writing commit messages for their reverts? They should have semantic commit messages just the same as any other commit.
Unless the point is that they're not following per-commit CD, and if you commit then revert that commit before a release was made. That sounds like a process failure. Which of course, process isn't infallible, and neither is the automated version management. If you screw up, use an escape hatch — just like reverting a commit that had previously gone through code review and been merged.
Re: change log generation. The article says change logs shouldn't have commit messages. I agree. Many tools (e.g. Changesets https://github.com/changesets/changesets) use the semantic commit type to sort change log entries, but require you to write those user facing change log entries separately.
Use some convention for git trailers then. Having “fix” or “feat” in the commit title does not provide any useful information to someone scanning the log.
How... how is this not obviously the absolute very most useful information?
When I encounter a bug in a dependency of mine. Before I worry about submitting a PR, the very first thing I do is grab my version number and check the commit logs for fixes since my version number.
If I'm trying to decide whether I should bother upgrading, I scan the log for new features.
It's the title, not the details. The commit message body should contain MUCH more detail than the title.
If you don't like it because it looks ugly. Sure, that's subjective. And actually, I agree. Because it's standardized though, Git interfaces could even be configured to trim this off and provide different visual styles for the different kinds of commits. The types could be used as search filters too etc.
Now, I get people don't like the look of them. Neither did I when I first saw them. Then I started using them and found them useful.
It's fine, people have different preferences, it's just a convention and it's not going to work for every project. The article itself just doesn't seem to hold any water.
If I'm at the point of contributing a PR to a dependency, I've already identified the root cause in detail. There's no way a change log should be going into that level of detail, or else you're just duplicating the Git log for no reason.
Will the change log make mention of fixing the bug? Perhaps. But I'm going to want to read the technical details of the fix to make sure they've specifically addressed my issue, and not just a similar problem. What is the performance impact of the fix? Are there security implications they've explained in the commit message.
I'm a software engineer, not an end user, I want the technical details of my dependencies.
If one is writing trailers and custom formatters, then probably the information that the formatter uses should be even more structured that sticking it in the subject line.
I quite dislike this style of writing titles. "Stop something". I seems very popular. It sounds very commanding and "I am definitely right about this". Why not write "In favour of something" or "A case against something" or something like that?
Why not be direct and advocate clearly for the position that you prefer? You don’t have agree with their position, but asking them to water down their words is weak sauce.
Oh please. Public discussion is always a balance, and to answer your question: if the content is nuanced, the title should be too.
If they mismatch some of your audience is unnecessarily put off.
Ill add: I am personally put off in the same way your parent comment is, because hard stances are usually wrong, and I like a bit of nuance in my life.
Not as bad as "considered harmful" imo but still mildly toxic. I think the point is taking one rando's personal preferences (I'd prefer we swap the order of A and B) and trying to make it sound like something more than it is.
> Not as bad as "considered harmful" imo but still mildly toxic. I think the point is taking one rando's personal preferences (I'd prefer we swap the order of A and B) and trying to make it sound like something more than it is.
Mildly toxic was the same but worse in my opinion.
I'd much rather people think deeply about summarizing their work. This helps others understand it but, more importantly, helps the developer understand what they did. If its hard to summarize, maybe it should be tightened up a little for instance. Enforcing a "schema" might help a tiny bit but also can cause people to check out a little as it can feel like just another meaningless process.
“The audience of a changelog is entirely different than the audience for a commit log!
A changelog is user-facing”
I'd say that ship has probably sailed. Most companies are happy with “Bug Fixes & Performance Improvements”.
At least if they're not going to put the effort in, then a generated changelog is better than nothing.
The best thing that I'd used for auto-updated software with weekly updates was to prefix user-facing visible commits with "uv:" Then each week we search for them and either use the text as-is or massage it slightly. We even got it into the product itself in the Help/Release-notes menu.
Funny to ask to stop doing something I don't do or never even heard of. I typically only mark database schema migrations or other major things with special prefixes.
The thing conventional commits are really helpful for is continuous delivery. Every merge to main can be automatically tagged with semver and shipped because the thought that goes into tagging and versioning has already been done by the developers when they wrote the commit message.
I fully recognise that it doesn't make sense for huge projects like the Linux kernel to do this. But for 99% of projects conventional commits combined with semver vastly improves the release process status quo and makes it easy to automate.
I like relying on `git tags` even in continuous delivery situations. `git describe` is often good enough for continuous delivery versioning `v1.2.3-4-gabcdef` can describe a commit exactly enough to make git happy and is semver-like enough to set expectations, even/especially if new `git tags` are only ever inserted on human discretion (this is breaking change so I need to tag a new major now). The only real debate with `git describe` format version numbering is if to better conform to semver expectations the first dash should be a plus or not and you can do that change with a quick regex if you feel it is worth it for whatever is enforcing your semver expectations (ordering versions correctly in a package manager, for instance).
`git describe` is easy to automate for CD, but can leave version number decisions to people via `git tag` choices (and/or GitHub Releases) rather than trying to guess from commit history magic keywords.
I do this on my OSS projects to automate semver bumps and it's amazing! At work, I also enforce "tags" (not git tags, just strings in the PR title) based on who cares about the change and then generate changelogs for the respective teams based on those "tags".
I can not say anything nice about conventional commits. The format takes up space in the most-read part of the message. The categories or types have little information. They can be replaced with an honest English verb embedded in the subject like a sentence. It also reads way better with just a sentence instead of three kinds of punctuation (:, (), !). Okay, I can tolerate an "area" in the subject. And that predates this conventio.
At my dayjob we make a webapp for non technical people. I can write a changelog for that just fine (in norwegian). The commit messages are irrelevant to the users. And demanding that all commits should be good enough for an end-user changelog? That's not happening for us anytime soon.
None of this is as good as "free array memory before it goes out of scope". This is better than `fix: memory leak` - which is what most people would do. It's also better than `fix: free array memory...` because `fix:` is redundant when you have a good message. I get people want to build automation around this stuff, but just do that in a footer of a commit message where humans don't need to see it.
Whole idea of CC is to write commits in away that is easy to generate change logs. If you utilize CC correctly or not, at best you get: commit log that harder to read, changelog that is hard to read and still requires you to write highlights (guess minor and path releases are fine).
Though the example in the actual specification, “fix: array parsing issue when multiple spaces were contained in string”, is more inconclusive (and frankly doesn’t really make sense as a description).
yep. I'm on the fence about types generally, but "fix:" saves/standardizes a bunch of phrases like "fix an issue where", "prevent" or having to invert the message by describing the solution instead.
Article is too opinionated IMO. I enforce CC on my projects because I don’t have the energy to police horrendous commit messages. It’s easy to enforce the CC format on the repo merge policy. I do it with the addition of a required issue ID as well.
If I only worked with seasoned devs, I wouldn’t use it, but that’s just the reality of my work. It also has a bonus of forcing AI agents to write in the same form as well instead of their random personal flavor. Precommit hooks stop everything before it gets in front of my eyes for review.
> I enforce CC on my projects because I don’t have the energy to police horrendous commit messages.
And does it actually accomplish that goal? I've been on several projects where someone pushed CC on the team with this reasoning. Every time my experience has been that you get the same crappy messages with a tag that may or may not be accurate.
BTW, AI absolutely knows how to bypass pre-commit hooks and will do so when they come up with some reasoning why their situation is an exception to the rule. I've watched them do it. The only way I've found to strictly enforce things on an agent (tests, linting, whatever) is to use a claude pre-command hook that will block git commit if the checks don't pass.
There's no benefit to any of this. Just write like human. It will be clear if it's a fix, or a refactor, or ?. Typically it isn't just one of those things.
I see more of these conventional commit-style comments recently and it feels like coming from Claude Code etc. It's a bit unsettling that not only training data but also random lines in the default system prompt affects this kind of software development norms in subtle and pervasive ways.
This is not without struggles. Many times the changelog updates are missed. You can try to catch this in code review, but that could also be missed. So you can try to automatically verify the changelog was updated, but you can't force that as a pass/fail check since not all changes require a user facing change. Or your project maintainers simply copy the commit message and paste it into the changelog, and at that point, why not just automate it with something like conventional commits?
Could/should the changelog be considered a first-class deliverable with care and attention provided? I think so, but I'm not in a position to exert direct control over that across dozens of repos and team members.
In my experience, LLMs are great at reviewing changelogs for potential gaps from a user POV (and even creating draft changelogs wholesale, if you're backfilling) based on git history.
I think some structure in commit messages is helpful, but not to the point where it gets in the way of effectively reflecting what the commit contains, why it was done, and any comments for future reference, e.g. potential regressions.
Conventional commits (especially with git emojis) show at a glance the blast radius of the change (eg whether it breaks the product itself or just some internal dev tools). Emojis help immensely when looking at dozens of commits at a time.
That information should still be in the commit messages. "No functional change intended." appears widely in FreeBSD commit logs when code is being refactored (or, rarely, restyled).
And the issue isn't whether you can remember what you changed yesterday; this is largely about making sure other developers can quickly identify relevant commits. If you're a solo non-OSS developer, this is entirely relevant to you.
Definitely agree that generating change logs from commits leads to confusing change logs for people that expect to see what changed between versions. A big long list of commits is too granular. A curated and summarized list of changes is much more in-line with what most people expect when reading a change log.
I have long despised Conventional Commits for pretty much these reasons. Yes, it’s structure, but it’s not useful structure. Of the five things it claims to enable, three are nonsense and the other two are actively bad.
And it’s ugly.
(But I suppose I am talking primarily about the first line part. The “BREAKING CHANGE” bit is potentially actually useful, though being incompatible with git-interpret-trailers despite leaning on git-interpret-trailers for other footers seems a bit crazy.)
Asides from the well made points here ('scope is more important than type' etc).
> something like fix, feat, chore, docs, or refactor
'Docs' are also part of the program, they need fixes too, and features need docs. If the docs don't match the features because they're not being updated when the code is, the docs are a lie and waste other developers time.
Also if you were writing a standard: why would you randomly abbreviate 'feature' but not 'refactor'? That sounds like a nitpick but standards require great thought, this is a bit of a smell that there hasn't been much thought into designing 'conventional commits'.
Finally: the name 'Conventional commits' is a land grab (reminds me of when someone made a JS Standard and called it 'StandardJS', ignoring every existing popular standard). From the article, the *actual* convention is 'scope: work"
Mine is “ticket id - Imperative phrase”. Then I write a “why” description of the changes if needs be. As for personal project, I quite like the scoped commits style.
I don't care much what it says as in "fix", "chore" etc, but for me the main benefit is breaking changes indicated with "<type>!", something like "feat!: ...
".
This makes neovim plugin manager highlight the change differently which brings attention to it when you update stuff.
So please do use it instead of complaining!
I do like the suggestion of
scope!: ...
if it will be treated the same way with breaking changes reactions.
terrible suggestion, people are awful at writing commit messages and the type is really helpful when you're reviewing history and want to know things at a glance
I really dont care about commit messages. Just create strict rules for branches that contains issue nr + description, and squash all commits on merging the PR.
As programmers I feel like we'll always nitpick and bitch over what the optimal setup is for rather mundane things (tabs v spaces, yada yada).
I'm not saying that conventional commits are God's given best way to structure a commit message, but they are a defined structure, and I find it much more effective and important that some expectations be set around commit messages, and I think conventional commits are as good as anything.
Like the author is making a big deal that they think scope is more important than type. I may tend to agree, but I think the difference between "fix(compiler)" and "compiler fix" is not exactly a hill I'd be willing to die on.
The tech industry has tons of things that became standards even if they weren't optimal. E.g. if one were starting from scratch I think any sane person would argue JSON should support comments (sorry but Douglas Crawford's rationale for not including comments never made sense to me), better defined numeric formats, etc. But it was better in many contexts than what came before it, so it became the standard. I could believe that there is some other format that differs a bit from conventional commits that is a little better, but not really better enough to want a whole other competing way of structuring comments.
The real takeaway is that different projects have different requirements.
In over 30 years of using source control, I've never once worked on something where it's useful to include the component (article calls it scope) in the description in a standardised way. It's obvious what components are affected based on where in the source tree the affected files are. Similarly "bug", "fix" or "feature" adds no useful value. It's important or it wouldn't be checked in.
The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all the information about what was done in the change, what's missing is the context about why.
Even on my solo projects I include a JIRA reference in square brackets before the description. If it's just something I randomly decided to fix during the course of development, I'll create a short 1 line JIRA to get an id and explain the why there.
It is useful if you automate generating release notes. Then your notes are grouped by new features first, then bug fixes after. This makes it a little easier for non-technical uses to read.
Commit messages are good release notes rarely.
it's usually a "something is better than nothing" situation.
If you have somebody willing to write custom release messages, that's definitely better; but conventional commits is better than nothing for it.
Is the benefit of using a separate source that you can include images or something else I’m missing? Couldn’t you include context in the commit body?
Pretty much everywhere I've worked recently enforces some kind of jira ticket number in the PR title
My main complaint with conventional commits always was that they don't include an issue number in the commit title. It's not even mentioned in their standards as optional or something.
To me this is almost the most important information in a commit message. I don't know how often in the last 15 years I was cross checking the issue description referenced by some old commit to get the full context of a change. I also felt that this habit is kind of standard - until i had to learn about "conventional commits".
I never got the hype.
I personally prefer including issues as git trailers:
Git has plenty of builtins for parsing and formatting these trailers, so you can easily create custom git log aliases that let you see them inline and parse them for use with CI.Personally, if I am skimming a change log that is already limited in characters, I don’t care about ‘XYZ-999999’ in the main commit message. It’s good to tag as a trailer but I’d much rather see what the commit did than the Jira issue it came from.
It's totally fine to put the issue number somewhere at the end of the commit message, and not in line 1.
Most tools cross-link them as long as #<issue-id> is mentioned anywhere in the message. It's also useful the other way around, open an issue and see all associated commits.
Yeah the ticket value falls off pretty quickly to me. If I pull that up and it's been a closed issue for years and code has been added, rewritten, people moved, and tons of other changes to where the ticket is just a historical artifact and doesn't need priority in the first line of the commit message.
IMO that is only a problem for those who demand that the issue key needs to go first in the subject (which again IMO is bad for readability). I don't see why you can't just stick it somewhere after all the conventional commits junk? Issue keys ought to be something that can be janked out based on a regex like an alphanumeric prefix followed by a number, so things like this "standard" have little need to set aside a space for it.
Personally (without conventional commits) I tend to put them at the end in parentheses if the commit has something to do with that issue. But if there is a stronger relationship like that it fixes the issue, I put a `Fixes` trailer in the message as well.
Interesting, I guess we've been doing it wrong this whole time, as we do `fix(ABC-123): some message here`, which ends up being linked great, renders very nicely into the automated release notes, etc.
It isn't a standard, it is a convention. You can set a standard within your team to include the ticket id in the commit message.
yeah this is the actual key. an actually useful title and a stable link to the discussion around the change.
conventional commits are pleasing, but questionable actual utility. the code speaks for itself. the actually useful information is a well chosen title and the context for the change.
Why do you even want the issue number in the commit title? I find that super annoying and unfortunately GitHub kind of forces it on you if you use merge queues.
It's fine for it to be in the description.
If i'm looking at git history, the ticket number is the most useful piece of info to get more context on the changes for me
It’s very helpful to know the motivation for the commit and if that motivation was tied to a client contract/feature. Especially in cases where a commit affects multiple files or even just one file so that all commits can be grouped into a feature/contract.
COMPANY-1234 in the title doesn't tell the reader all that much about the the feature or motivation. It does tell the client, but I'm not seeing why that is better than having it in the description as a tag, or some other nice way of extracting it.
Least of all when that ticket is older and so much of the code and the company has changed too. Like sometimes useful historical context sure but worth putting in the first line of a commit? I put it in the body with a link to the ticket or tickets as a footer, if someone wants historical context it's there.
The use of the word "chore" in many users of conventional commits has always riled me. I've always tended to favour the "linux kernel"[0] style of commit subject, which thankfully gets a mention here.
[0] https://www.kernel.org/doc/html/v7.0/process/submitting-patc...
Completely agree, the attitude implied by “chore” is very off-putting to me. As if the rest should all be marked “fun” or “indifferent”. That kind of emotional judgement doesn’t belong in a commit message.
I’ve never personally used the chore term, but it doesn’t bother me to see it and I don’t feel it has a negative connotation.
Cleaning my kitchen after a meal may be a chore, but it’s not an intrinsically bad or unpleasant experience most of the time, it’s just good hygiene and afterwards I have the satisfaction of things being clean. Not cleaning the kitchen feels way worse to me as it ultimately leads to other far more unpleasant situations.
Such it is with updating dependencies, it generally needs to be done, so it’s good to do it, but it’s in no way noteworthy, so chore describes it perfectly, to me it signals that: “it’s work that needed to be done, but not for a feature, functionality change or bug fix on this particular code base, so you’re unlikely to see much change”.
I don't personally see people write this message (though I'm sure they do) but dependabot and similar use it.
So now I associate it an automated pr vs authored
I remember HN discussions pre-AI where people staunchly defended the use of that prefix.
I use chore quite a bit in my human written commit messages.
I found an alternative word: "upkeep"
Same idea without the pejorative aspect.
It is bad terminology, yes. But also - a pretense that you know the overarching influence of a commit ahead of time, which you don't - but once you have conventional commits everyone on the team and the LLMs have to spend time/tokens inventing that stupid nomenclature.
You might enjoy Rich's take: https://richvdh.org/conventional-commits-considered-harmful....
Richard van der Hoff that is, not Rich Hickey which I first thought had published something new and opinionated again.
Odd. The main reason to use this style of commit message is for CI/CD automation.
EDIT: I didn't see this covered in the article on my first pass. It is covered though. My apologies.
The type of the commit informs the automated workflows how to handle the commit. This is why it comes first.
For example, if you're performing CD, if you only commit a bunch of `fix: ` then only your semantic versioning patch version number is incremented. If you commit a `feat: ` then it's a minor version is bump. `feat! ` is a major version bump.
Even if you're not using CD for releases, semantic commit messages are sometimes used to automate change log generation. Granted, your change logs should not typically include the Git commit messages themselves — those are developer facing, not user facing.
The article addresses both of these pretty clearly. Semantic versioning gets borked with reverts and the automatic changelog is targeting the wrong audience
The article is wrong about reverts (in my opinion). If a breaking change is introduced, and then removed, the removal should also most likely be considered a breaking change (both the addition and removal are changing your API). So it is correct that a major version bump should occur when reverting. Once a package has been published, the ship has sailed.
The issue is that if there was no release in between, or only a beta or similar, you now have two breaking changes indicated by the commits, although in sum there is none since the last official release.
That's true, but depends on your workflow and release strategy.
If you are releasing upon every push to main/master (following what semantic release and conventional commits provides you in terms of automation), then it makes sense to perform major version bumps for the reverts.
If you have a manual release strategy, then it might not make sense to use these tools in the way they have been designed.
If you have actual dependents in a SemVer fashion, then this isn’t useful for those still on the prior version. What you’d rather do is decrement the major version again because it’s compatible with the prior version again. Those dependents who already upgraded to the interim version have to consider another breaking change regardless.
And if you don’t have these kinds of dependents, then the versioning scheme isn’t important anyway.
release-please[0] allows you to do a manual version override in a commit, which would allow you to decrement the major version upon reverting a breaking change
I think that could be simplified, so the tool can tell that a commit is reverting a breaking change and thus the version should be decremented, but at least there's an escape hatch.
[0]: https://github.com/googleapis/release-please
My apologies, I missed this on first read due to the indentation style. That said, I don't agree on the commentary.
Why on Earth are people not writing commit messages for their reverts? They should have semantic commit messages just the same as any other commit.
Unless the point is that they're not following per-commit CD, and if you commit then revert that commit before a release was made. That sounds like a process failure. Which of course, process isn't infallible, and neither is the automated version management. If you screw up, use an escape hatch — just like reverting a commit that had previously gone through code review and been merged.
Re: change log generation. The article says change logs shouldn't have commit messages. I agree. Many tools (e.g. Changesets https://github.com/changesets/changesets) use the semantic commit type to sort change log entries, but require you to write those user facing change log entries separately.
+1 I used this style to version bump, and wish the article gave suggestions on working alternatives.
Lately I use CalVer instead of SemVer, so it hasn't been an issue. I like the idea of smart auto-bump for versions.
Use some convention for git trailers then. Having “fix” or “feat” in the commit title does not provide any useful information to someone scanning the log.
How... how is this not obviously the absolute very most useful information?
When I encounter a bug in a dependency of mine. Before I worry about submitting a PR, the very first thing I do is grab my version number and check the commit logs for fixes since my version number.
If I'm trying to decide whether I should bother upgrading, I scan the log for new features.
It's the title, not the details. The commit message body should contain MUCH more detail than the title.
If you don't like it because it looks ugly. Sure, that's subjective. And actually, I agree. Because it's standardized though, Git interfaces could even be configured to trim this off and provide different visual styles for the different kinds of commits. The types could be used as search filters too etc.
Now, I get people don't like the look of them. Neither did I when I first saw them. Then I started using them and found them useful.
It's fine, people have different preferences, it's just a convention and it's not going to work for every project. The article itself just doesn't seem to hold any water.
This is what a changelog is for
It's really not.
If I'm at the point of contributing a PR to a dependency, I've already identified the root cause in detail. There's no way a change log should be going into that level of detail, or else you're just duplicating the Git log for no reason.
Will the change log make mention of fixing the bug? Perhaps. But I'm going to want to read the technical details of the fix to make sure they've specifically addressed my issue, and not just a similar problem. What is the performance impact of the fix? Are there security implications they've explained in the commit message.
I'm a software engineer, not an end user, I want the technical details of my dependencies.
If one is writing trailers and custom formatters, then probably the information that the formatter uses should be even more structured that sticking it in the subject line.
No no. You see we need to get rid of conventional commits so AI can make commits easier.
I’m pleased to report that TFA is unrelated to AI.
I quite dislike this style of writing titles. "Stop something". I seems very popular. It sounds very commanding and "I am definitely right about this". Why not write "In favour of something" or "A case against something" or something like that?
Why not be direct and advocate clearly for the position that you prefer? You don’t have agree with their position, but asking them to water down their words is weak sauce.
Oh please. Public discussion is always a balance, and to answer your question: if the content is nuanced, the title should be too. If they mismatch some of your audience is unnecessarily put off.
Ill add: I am personally put off in the same way your parent comment is, because hard stances are usually wrong, and I like a bit of nuance in my life.
Our interest in a statement is piqued more when it challenges our worldview. It's impolite to a lot of people, but the attention economy rewards it.
Not as bad as "considered harmful" imo but still mildly toxic. I think the point is taking one rando's personal preferences (I'd prefer we swap the order of A and B) and trying to make it sound like something more than it is.
> Not as bad as "considered harmful" imo but still mildly toxic. I think the point is taking one rando's personal preferences (I'd prefer we swap the order of A and B) and trying to make it sound like something more than it is.
Mildly toxic was the same but worse in my opinion.
I came to say something similar.
I don't like conventional commits much neither, but let the people use whatever they want!
https://knowyourmeme.com/memes/stop-doing-math
There is a meme that inspires some of this genre of title, fwiw
Because you don't get attention if you don't write deliberately inflammatory content.
I'd much rather people think deeply about summarizing their work. This helps others understand it but, more importantly, helps the developer understand what they did. If its hard to summarize, maybe it should be tightened up a little for instance. Enforcing a "schema" might help a tiny bit but also can cause people to check out a little as it can feel like just another meaningless process.
“The audience of a changelog is entirely different than the audience for a commit log!
A changelog is user-facing”
I'd say that ship has probably sailed. Most companies are happy with “Bug Fixes & Performance Improvements”. At least if they're not going to put the effort in, then a generated changelog is better than nothing.
The best thing that I'd used for auto-updated software with weekly updates was to prefix user-facing visible commits with "uv:" Then each week we search for them and either use the text as-is or massage it slightly. We even got it into the product itself in the Help/Release-notes menu.
Funny to ask to stop doing something I don't do or never even heard of. I typically only mark database schema migrations or other major things with special prefixes.
I like this idea, but could see it working better as a git trailer to avoid adding noise to git log
The thing conventional commits are really helpful for is continuous delivery. Every merge to main can be automatically tagged with semver and shipped because the thought that goes into tagging and versioning has already been done by the developers when they wrote the commit message.
I fully recognise that it doesn't make sense for huge projects like the Linux kernel to do this. But for 99% of projects conventional commits combined with semver vastly improves the release process status quo and makes it easy to automate.
I like relying on `git tags` even in continuous delivery situations. `git describe` is often good enough for continuous delivery versioning `v1.2.3-4-gabcdef` can describe a commit exactly enough to make git happy and is semver-like enough to set expectations, even/especially if new `git tags` are only ever inserted on human discretion (this is breaking change so I need to tag a new major now). The only real debate with `git describe` format version numbering is if to better conform to semver expectations the first dash should be a plus or not and you can do that change with a quick regex if you feel it is worth it for whatever is enforcing your semver expectations (ordering versions correctly in a package manager, for instance).
`git describe` is easy to automate for CD, but can leave version number decisions to people via `git tag` choices (and/or GitHub Releases) rather than trying to guess from commit history magic keywords.
I do this on my OSS projects to automate semver bumps and it's amazing! At work, I also enforce "tags" (not git tags, just strings in the PR title) based on who cares about the change and then generate changelogs for the respective teams based on those "tags".
Want machine-readable? Use the footers/trailers.
I can not say anything nice about conventional commits. The format takes up space in the most-read part of the message. The categories or types have little information. They can be replaced with an honest English verb embedded in the subject like a sentence. It also reads way better with just a sentence instead of three kinds of punctuation (:, (), !). Okay, I can tolerate an "area" in the subject. And that predates this conventio.
At my dayjob we make a webapp for non technical people. I can write a changelog for that just fine (in norwegian). The commit messages are irrelevant to the users. And demanding that all commits should be good enough for an end-user changelog? That's not happening for us anytime soon.
Use footers/trailers instead.
The author's example of a conventional commit is not correct anyway IMO, which is maybe why they think the "fix" part is redundant:
> fix: prevent foo from bar'ing
The whole idea of conventional commit is:
> fix: [problem]
so the correct conventional commit would be:
> fix: foo bar'ing
which is succinct and perfectly fine.
None of this is as good as "free array memory before it goes out of scope". This is better than `fix: memory leak` - which is what most people would do. It's also better than `fix: free array memory...` because `fix:` is redundant when you have a good message. I get people want to build automation around this stuff, but just do that in a footer of a commit message where humans don't need to see it.
Whole idea of CC is to write commits in away that is easy to generate change logs. If you utilize CC correctly or not, at best you get: commit log that harder to read, changelog that is hard to read and still requires you to write highlights (guess minor and path releases are fine).
What you describe doesn’t match <https://www.conventionalcommits.org/en/v1.0.0/>’s examples, or any practice I’ve ever seen.
> fix: prevent racing of requests
Though the example in the actual specification, “fix: array parsing issue when multiple spaces were contained in string”, is more inconclusive (and frankly doesn’t really make sense as a description).
I agree, the default change logging using something like semantic-release would result in this, which feels way off:
# Bug Fixes
- foo bar'ing
yep. I'm on the fence about types generally, but "fix:" saves/standardizes a bunch of phrases like "fix an issue where", "prevent" or having to invert the message by describing the solution instead.
Previously: https://blog.julik.nl/2020/04/do-not-use-tickets-in-commit-t... with honorable mention of conventional commits. There is nothing conventional about them - it's ceremony that's wasting valuable characters that can have a better use.
The article is 100% on the mark.
Article is too opinionated IMO. I enforce CC on my projects because I don’t have the energy to police horrendous commit messages. It’s easy to enforce the CC format on the repo merge policy. I do it with the addition of a required issue ID as well.
If I only worked with seasoned devs, I wouldn’t use it, but that’s just the reality of my work. It also has a bonus of forcing AI agents to write in the same form as well instead of their random personal flavor. Precommit hooks stop everything before it gets in front of my eyes for review.
> I enforce CC on my projects because I don’t have the energy to police horrendous commit messages.
And does it actually accomplish that goal? I've been on several projects where someone pushed CC on the team with this reasoning. Every time my experience has been that you get the same crappy messages with a tag that may or may not be accurate.
BTW, AI absolutely knows how to bypass pre-commit hooks and will do so when they come up with some reasoning why their situation is an exception to the rule. I've watched them do it. The only way I've found to strictly enforce things on an agent (tests, linting, whatever) is to use a claude pre-command hook that will block git commit if the checks don't pass.
There's no benefit to any of this. Just write like human. It will be clear if it's a fix, or a refactor, or ?. Typically it isn't just one of those things.
I'm quite fond of vimscript legend Tim Pope's guidance on writing commit messages.
https://tbaggery.com/2008/04/19/a-note-about-git-commit-mess...
I totally agree.
If one needs to put metadata in commits, usually better to just put it in a Git trailer.
https://git-scm.com/docs/git-interpret-trailers
`Co-authored-by: Alice` is a common one, but you can have anything in there.
So much commit hygiene and fuss appears git induced. Use something other than git and the problems disappear.
I think any notation is use case specific and should be adapted to beat serve its domain.
However, actually writing a good commit message is an art form few have mastered.
I wrote a small natural language linter to teach my teams meaningful technical writing: https://github.com/codingjoe/word-weasel
I see more of these conventional commit-style comments recently and it feels like coming from Claude Code etc. It's a bit unsettling that not only training data but also random lines in the default system prompt affects this kind of software development norms in subtle and pervasive ways.
I've seen Claude Code aggressively use Conventional Commits, even when the project its working on doesn't use them.
There’s a much less awkward way to keep a change log:
Keep a change log.
This is not without struggles. Many times the changelog updates are missed. You can try to catch this in code review, but that could also be missed. So you can try to automatically verify the changelog was updated, but you can't force that as a pass/fail check since not all changes require a user facing change. Or your project maintainers simply copy the commit message and paste it into the changelog, and at that point, why not just automate it with something like conventional commits?
Could/should the changelog be considered a first-class deliverable with care and attention provided? I think so, but I'm not in a position to exert direct control over that across dozens of repos and team members.
> Many times the changelog updates are missed.
In my experience, LLMs are great at reviewing changelogs for potential gaps from a user POV (and even creating draft changelogs wholesale, if you're backfilling) based on git history.
I 100% agree. I found https://keepachangelog.com/en/1.1.0/ as I was writing the article which advocates for exactly this!
I have never been involved in a project where people make good commits. Having a convention at least forces people to make thoughtful one-liners.
I think some structure in commit messages is helpful, but not to the point where it gets in the way of effectively reflecting what the commit contains, why it was done, and any comments for future reference, e.g. potential regressions.
As a solo developer, I rarely struggle to remember what changed yesterday. I often struggle to remember why I made a decision six months ago.
Conventional commits are most valuable to me as historical context rather than as a release-management tool.
The larger the project becomes, the more useful that context gets.
This sounds like what regular commit messages do. How are conventional commits specifically helpful?
Conventional commits (especially with git emojis) show at a glance the blast radius of the change (eg whether it breaks the product itself or just some internal dev tools). Emojis help immensely when looking at dozens of commits at a time.
That information should still be in the commit messages. "No functional change intended." appears widely in FreeBSD commit logs when code is being refactored (or, rarely, restyled).
And the issue isn't whether you can remember what you changed yesterday; this is largely about making sure other developers can quickly identify relevant commits. If you're a solo non-OSS developer, this is entirely relevant to you.
This entire essay is just about how it should be "<scope> <optional type>" instead of "<type> <optional scope>"?
Definitely agree that generating change logs from commits leads to confusing change logs for people that expect to see what changed between versions. A big long list of commits is too granular. A curated and summarized list of changes is much more in-line with what most people expect when reading a change log.
I have long despised Conventional Commits for pretty much these reasons. Yes, it’s structure, but it’s not useful structure. Of the five things it claims to enable, three are nonsense and the other two are actively bad.
And it’s ugly.
(But I suppose I am talking primarily about the first line part. The “BREAKING CHANGE” bit is potentially actually useful, though being incompatible with git-interpret-trailers despite leaning on git-interpret-trailers for other footers seems a bit crazy.)
Couldn't agree more with this. The commit type tells me almost nothing and just wastes my time skipping over it. Scopes are way more useful.
Many great developers seem to agree, based on the list of conventions use by the infrastructure scale projects covered in the article.
The proposal, https://scopedcommits.com/, is not that different.
My gripe about conventional commits is the redundancy: fix(ci): fix the foobar
Asides from the well made points here ('scope is more important than type' etc).
> something like fix, feat, chore, docs, or refactor
'Docs' are also part of the program, they need fixes too, and features need docs. If the docs don't match the features because they're not being updated when the code is, the docs are a lie and waste other developers time.
Also if you were writing a standard: why would you randomly abbreviate 'feature' but not 'refactor'? That sounds like a nitpick but standards require great thought, this is a bit of a smell that there hasn't been much thought into designing 'conventional commits'.
Finally: the name 'Conventional commits' is a land grab (reminds me of when someone made a JS Standard and called it 'StandardJS', ignoring every existing popular standard). From the article, the *actual* convention is 'scope: work"
- Linux
- FreeBSD - Git - Go - nixpkgsIn practice, when conventional commits are used with git emojis, they look like “scope: what is done” already (“<emoji> <issue-id> scope: …”)
And then you have me, using gitmoji
Mine is “ticket id - Imperative phrase”. Then I write a “why” description of the changes if needs be. As for personal project, I quite like the scoped commits style.
I don't care much what it says as in "fix", "chore" etc, but for me the main benefit is breaking changes indicated with "<type>!", something like "feat!: ... ".
This makes neovim plugin manager highlight the change differently which brings attention to it when you update stuff.
So please do use it instead of complaining!
I do like the suggestion of
scope!: ...
if it will be treated the same way with breaking changes reactions.
terrible suggestion, people are awful at writing commit messages and the type is really helpful when you're reviewing history and want to know things at a glance
I really dont care about commit messages. Just create strict rules for branches that contains issue nr + description, and squash all commits on merging the PR.