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.
Defined structure does not constitute quality. A commit message can be loosely structured, but be very insightful and good at communicating the nature of the change. On the flip side, one can make a very structured but confusing or non-informative commit message.
I generally tend to agree with the author, conventional commits do not solve the core issue of the poor commit messages problem.
Conventional commits made it easier to generate changelogs and automate semantic version bumps. I suppose LLMs can usually do that the right way with looser structure, but in the before times it made a lot more sense, and even now is much less ambiguous
They're hand-waved away by saying the changelogs are bad and the semver isn't always accurate. While I mostly agree with, that doesn't mean they don't provide _some_ value. You get categorized changelogs (even if the messages are technical) and semver that's generally correct. The alternative of good changelogs and perfect semver isn't free.
why is "solving" the issue somehow the bar? software engineering has more practices rooted in psychology than engineering, its a moving and ambiguous target. Using conventional commits gives you a framework and mechanism that undoubtedly improves contribution semantics.
In what context does wasting your first characters on fix vs feat matter?
PRs are going to have an explanation that has way more detail than necessary to figure that out quickly.
One lines tend to be (for me) in a situation where the difference is immaterial. If I am rapid firing through history I need to know what you did not why you did it.
Again I am not claiming that these are bad or even that they aren't good.
I am specifically disagreeing that any change is automatically good, that isn't true.
> Using conventional commits gives you a framework and mechanism that undoubtedly improves contribution semantics.
I do not want to contribute to a project using conventional commits. I have consistently found, that I am unable to decide what the "type" of a commit even is and I feel unnaturally caged in into how I would split up commits, by having them be restricted to types (it doesn't help that the conventional commits I've seen appear to decide the type by fair dice roll).
Discouraging contributions does not "undoubtedly improve contribution semantics".
It’s the linting argument all over again. I don’t give a shit what the style is. I give a shit that it’s consistent. Form whatever opinion you want about how you want to format your code, structure commit messages etc. I don’t really care, if you want to start every commit with “poop(fix): pooper my commit message”, as long as you’re consistent about it and enforce it programmatically you have my emphatic support
This comment assumes you are picking between a conventional commit message or something better. But the reality is you are almost always picking between a conventional commit and Nothing.
That is only true of semantically equivalent things.
Tabs vs spaces don't matter they are equivalent.
But consistency is only better when it is an improvement.
It is fundamentally important that convential commit is better for adopting it to be an improvement.
After all in your example wasting the first four characters of your commits with poop would objectively reduce the quality of your commit history, whether or not it was consistent.
> Tabs vs spaces don't matter they are equivalent.
Just to nitpick (because what else is this thread about? :))
They aren't equivalent! Tabs carry more semantic information than spaces. 1 Tab character == 1 Level of nesting
Space-based systems _can_ provide the equivalent semantic information if they are 100% consistent.
...but part of the argument in favor of spaces is that they allow an escape hatch of the strict indentation in order to allow pleasing visual alignments.
I end up thinking that conventional commits is a good idea because you can make tooling force people to at least put one iota of thought into what goes in a commit message. I've had to review so many commits with the subject "small fix" that was not in fact a small fix.
I work with legacy code and am regularly reading commit messages from 10-15 years ago while figuring out what was going on several teams past. It's also why I'm against squash-merges, there have been plenty of times a commit was in the middle of a chain of commits and the helpful context would have been erased if we had squashes in svn.
I don’t have a horse in the race, but the OP objections ring hollow to me.
- scope is important: true, but isn’t that derivable from the commit contents? An important sanity check on a diff is to look at the paths touched. (A “test” diff should not modify prod auth code.) but if you want to see this from —oneline, sure, I think feat(auth): is better than feat:
- wrong audience: I don’t agree. feat commits _should_ actually describe the product-facing changes. You _should_ curate a nice stack with your no-op refactor changes first, then your small new feature change atop. This is the most helpful thing to include in a diff comment. You should put anything technical in comments so they are not lost, “why I chose algorithm X” belongs in a comment or DECISIONS.md. These are all tedious things that only psychos bother doing in a commit history at a fast moving company, but on OSS projects I think it’s much more important to stash context in the commit messages.
I'm not yolkedgeek but I can give my own answer: EDN has tags. Tags start with `#` and are followed by a symbol (which is a lot like an identifier except that a lot of punctuation is allowed in symbols, because EDN derives from Lisp syntax rules). The `/` character is used for namespacing, and a user-defined tag must use a namespace. The tag meaning is application-defined, but there are a couple standard tags with well-defined meanings:
#inst "1985-04-12T23:20:50.52Z" = an instant / timestamp in RFC 3339 format
#uuid "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" = a GUID/UUID
More tags could be defined by the standard later, because the entire unprefixed namespace is reserved. But just having a well-defined way to represent timestamps and UUIDs is an immense win over JSON, where you have to somehow know (based on what you were expecting to receive) that this string should be parsed as a timestamp or a GUID.
Also, user-defined tags will often be used to represent a class:
#myapp/Person {:first "Fred" :last "Mertz"}
Again, no need to know (based on what you were expecting) that this particular object is an instance of Person; the data transfer format tells you what class it is. JSON has to add a field, and what field it is will vary from application to application so it's usually not possible to write a universal parser. One server might generate { "__type": "Person", "first": "Fred", "last": "Mertz } while another one does { "$$class": "Person", "first": "Fred", "last": "Mertz }, for example.
EDN also has syntax defined for sets, but that's a smaller win over JSON, because it's not often necessary to declare that something is a set. Still, there are times it's helpful; it's certainly not a bad thing to have a set syntax.
Also, EDN has comments built in to the system. Two kinds, one line-based comment (useful for actual comments, e.g. when you use EDN as a config format), and one that comments out the next thing in the file (useful for temporarily commenting out an entire section with a single token, or for removing ONE item temporarily from a list that's all on the same line so line-based comments are difficult). Because Douglas Crockford didn't envision JSON as being used for config, he forbade comments in JSON, and people have been coming up with competing proposals for putting comments back in ever since. (Thankfully, nearly all the proposals interoperate, because all of them sensibly use Javascript comment syntax, so it doesn't matter if the file is JSONC or HuJSON or JSON5, the comment syntax is the same).
But the biggest win for EDN is tags, which can convey type information outside the data structure. JSON has to use something inside the data structure to convey type information, and there's always that small chance that the name chosen (__type or $$class or whatever) will collide with a property of the actual object that was supposed to be serialized.
I get tags and atoms. It seems like the problem with class serialization is somewhat arbitrary though. It seems like both sides need the object schema ahead of time, in which case the schema can flag how it sdould be IDd / tagged.
I also wonder if atoms can be reduced for low-bandwidth transmission. Naïvly, you could just prepend a lookup table for multiple-use atoms.
I guess it seems more like niche, additional features when GGP seemed to be claiming a big step up.
I haven't used EDN, but I know YAML has an equivalent feature, and that had been a security issue in some instances because it deserialized into objects the system wasn't expecting. Perhaps their deserializer had learned from that doesn't have that issue?
Haven't used EDN myself but from a read through the docs, I'm pretty sure that on user tags, the deserializer just says "Here's the tag, and here's the object it was tagging" and lets the consuming code decide what to do with the tag. (And on canonical tags like dates and GUIDs, there's no security risk to deserializing them as the recipient language's version of timestamps and UUIDs).
Actually, https://github.com/edn-format/edn says "It is envisioned that a reader implementation will allow clients to register handlers for specific tags. Upon encountering a tag, the reader will first read the next element (which may itself be or comprise other tagged elements), then pass the result to the corresponding handler for further interpretation, and the result of the handler will be the data value yielded by the tag + tagged element, i.e. reading a tag and tagged element yields one value. This value is the value to be returned to the program and is not further interpreted as edn data by the reader."
So if the client is specifying the handlers, then it's up to the client's handler implementation to sanitize the incoming data before instantiating the objects. And since the client supplies the list of handlers, the only tags that will be handled are ones the client was expecting. Assuming sanitizing the incoming data before instantiating objects is done correctly, I don't see any way for that to become a security issue.
I’m all for standardization but you could just use this argument to keep any suboptimal status quo in place. XML is good enough and a standard. SOAP is good enough and a standard. etc.
The claim is that Conventional Commits are good enough and standardized enough that having another structure isn’t really worth it. But “worth it” is subjective. I’d say that if you are making commits and reading PRs every work day, and the conventional commits format causes a little bit of friction, that friction can add up. Having another option other than seeing conventional commits as a law of nature gives options for teams who prefer it. (Most teams aren’t generating changelogs anyway.)
The new structure needs to be "better enough" that it overcomes the built-in deficits of the older structure, and it can't introduce so many new problems that make it a net negative.
JSON was definitely a huge improvement in simplicity and readability compared to XML for many contexts. Similarly REST a much better option than SOAP (and all of these are examples of the general over-engineered, design-by-committee architectures that came out of the late 90s/early 00s - see also the original EJB spec - before a larger trend towards simplicity and ease of use won out).
But it this case, a lot of the differences just feel like potayto/potahto, i.e. minor stylistic preferences. And I have been in jobs where more than 50% of my time was doing code reviews, and while often there were e.g. some linter rules or whatever that I found suboptimal, it was a lot easier to just go with it than waste the energy to have the battle over why I think for loops are actually OK.
I don't need a standard for this. This is just noise. There are some people who have some sort of mental ailment that makes them obsessively want to introduce "structure" "scheme" "patterns" where it is just innately nonsense. You do you, but stop trying to force it on people.
Reminds me of the "scrum master" adjacent folks who could never cut it writing code and then branched into all kinds of things like "Git Flow" when having never understood Git to begin with. Peak bikeshed territory.
Reminds me of a place I worked at where a "naming committee" had to approve variable names. And no, you could not use "i" as an index in a one-line loop.
> One letter variables are supposed to be used in scopes that fit on the screen completely.
Exactly, and ideally in less space than that. If you have something like:
for (i=0; i<10; i++) {
foo(i);
bar(i);
}
There is no point in using a "descriptive" name for the index. It's completely obvious what's going on. Anything more verbose would just hamper readability.
hence tabs. just configure your display for the width you like.
though I do wish more editors had some kind of "ignore the spacing, display it semantically like [this]" and just let you insert whatever you wanted, converted to whatever is nearby, and didn't touch lines you didn't create. there's no reason to even have the debate or care about inconsistencies, you can essentially always* convert between them losslessly in terms of behavior.
The next iteration is "smart tabs", where indents are stored as spaces in files for consistency, but when using an editor it recognizes that something special is going on, and offers you a tab-like experience.
which they kinda already do, yea. I just want it to be stronger, and to correct indentation that doesn't follow your formatting rules (which I have not seen / is not widespread). kinda like a `gofmt` overlay on a file, rather than modifying the file directly.
as a bonus, this could also make `goto fail;` errors more obvious.
> 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 big deal is not that scope is more important then type, the big deal is that natural language allows you to formulate things to emphasize whatever you consider important, and by forcing everything into a specific format this information is lost. There's a reason we have formats like markdown and plaintext, not just JSON.
Conventional Commits still have a free-form description section. The structure just introduces some standardized elements - and this is common in all types of written communication. Books have tables of contents, chapters have titles, letters have salutations, etc. etc.
Great perspective! As a sidenote, I really like json5 for everything that would be needed for a human to read and it has great support everywhere. It fixes so many of JSONs shortcomings like 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.
Absolutely not. Commit messages should never be automatically passed through to the end-customer. I also worked in a place that tried it once and it was a disaster. Sure, a list of commit messages can be a useful start as a list of things that might want to be put in the release notes, but very rarely is the developer the right person to be explaining those changes to the end user.
If a developer is being asked to do that, it's a good sign that the PM isn't doing their job properly.
For GH issues you can always navigate back to the PR discussion (which should have linked issues and other pointers in it) from the commit.
Of course when we switched to GH issues, we largely abandoned JIRA and years later the instance got turned off and deleted. Now all those JIRA tags are entirely useless.
IMO that actually argues for tight coupling between your issue tracker and your git repo. And what you really want is portability (which I don't see how you get other than with tight coupling). Ideally there would be open standardized formats, but as it is, github is the 800# gorilla that defines the format and as long as gitlab and other clones can slurp in github project metadata (or at least PRs) then that effectively gets you closer.
But any way... Fixed, immutable pointers to an Atlassian product that you might not be using in 5 years is not a good policy. I'd sooner accept the policy that the git commits needed to stand entirely on their own and all the information about the "why" of the change needed to be baked into the git commit or the comments in the source (I think that fails, though, since everyone is overly terse in git commits and summarizes issues and loses information--and the back-and-forth dialog in a PR discussion is useful because it contains more than just one person's voice summarizing the reason for the change).
> we largely abandoned JIRA and years later the instance got turned off and deleted
Sorry to be nitpicky, but why did you abandon a tool that contained a lot of valuable knowledge? That's not the fault of GH nor JIRA, that's your fault. At least you'd back up descriptions + comments from these JIRA sources.
That isn't true though. It's very easy to export your data from JIRA. From your board, go to the List tab, filter the items to whatever you want, and then click ... and you can export the data in various different formats. Exporting as XML dumps everything.
You can trivially export your data from JIRA. If the parent experienced a situation where valuable information was lost because the instance was deactivated, that's not JIRA's fault.
I didn't abandon it, it was run by a different team, and we were one consumer of it. When the organization switched from Jira to GH issues the Jira was kept running for years, but nobody got the information into GH issues. Eventually the Jira was shut down, certainly by the time the company got acquired.
> Of course when we switched to GH issues, we largely abandoned JIRA and years later the instance got turned off and deleted. Now all those JIRA tags are entirely useless.
We did Bugzilla -> FogBugz -> Jira. Almost all the data was lost every time, no one bothered with migration except for the maintenance project. Worse, even on Jira we lose cases as teams end and hand off the code, and the Jira project is closed so no one else can access it.
We've also done cvs -> svn -> git. All the commits have survived migration.
I do keep including cases in the commits messages, if nothing else it'll help link things together in the future, but never rely on them for context a future maintainer might need.
> 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.
The "why" is THE thing that needs to go in the git commit message. Capturing "why" is the entire point of that message and slapping a link to some external (and eventually absent) resource is not a good substitute.
1. Usually the commit message is often too short to capture the "why" adequately.
2. It is very beneficial to capture the why in one single source of truth, and that usually is not the Git commit message in a business context. Hate on Jira all you want, but if you capture the "why" there, you can add comments, view history, add rich context, link dependencies, add rich context, etc. Can't do that in a Git commit message.
My ire is more directed at github PRs than Jira... but the same basic idea applies. You want a single source of truth and you want that as close to the origin (the code) as possible. Your history, dependencies, etc. are all in git already and can be highlighted there if appropriate. For general comments, git notes covers that.
Business (ie. $work) will dictate whatever it wants and that is what get used but for anything I personally have control over, everything goes in the repo itself to prevent platform lock-in. For example, github's been going downhilll lately but all those projects with their history in PRs, etc. now needs to exfiltrate all that data somehow.
Jira contains discussion and requirements. It can meander for months before the right action is chosen. It can be important to have background, but it replaces the mailing list discussion that led up to the change, it does not replace the commit message.
The commit message is writen in retrospect and is written for someone with the code in front of them to explain why this change was made, and why it was done in this particular way.
If your commit message is too short then than is your problem right there. The easy fix is you taking five seconds out of your busy day to save an hour for you readers.
Have you seen how commit messages are written for git itself, or for the Linux kernel? Let me help you by linking the currently latest commit in the github mirror of git, it is not chosen to be particularly good or bad but is pretty representative of how git developers write commit messages:
https://github.com/git/git/commit/b809304101
As you can see, without knowing much of the specifics of the code, we can get an idea why this change was made the way it was. There is a certain art to writing short and concise commit messages, but the same is true for code itself. Some, but comparably very little, practice is required.
I find bug trackers and source control fad change several times over the life of my code. A number from a ticket system we no longer use is not helpful.
But a number from a ticket system you are using is helpful and vastly more log messages will be read during the time when it’s active than after it’s been retired/replaced.
Respectfully, I disagree. A good commit message to me is something like:
[PRJ-123] Changed blah to foo
Blah didn't handle the wangle flange properly in some cases, foo is a better fit for customer requirements.
The "why" that justifies the change, is already contained in the JIRA ticket PRJ-123 and explains exactly what the customer requirement was that necessitated the change. It will almost certainly contain a lot of detail that isn't relevant to the commit message, because that isn't the place to be documenting customer requirements, and probably relates to a number of other tickets. Perhaps the code itself might have a comment explaining the code change, if it's a non-obvious implementation, but otherwise the ticket is the best place for that information.
Additionally, if a change requires multiple commits, you don't want to be repeating the justifications for the entire feature in every commit message. It's redundant. But the commits will all be tied together by the ticket reference in the commit message.
Hah, maybe its the difference between why as in "this addresses problem X" and why as in "because those jerks in pre-sales sold another imaginary product"
I think the commit ought to describe the purpose of the change in terms of its result for the software's intended use. Feel free to hide the business/political drama behind a ticket number.
This gets down to a more fundamental tension. Are commit messages to communicate between developers? To communicate from developer to consumer? Or some kind of project manager golem? In practice, it is usually some constantly wandering attempt to be a blend of these.
The last part is easy to answer. Commit messages are solely for developers IMHO. The communication between developer and customer / product manager should be via the ticket system.
That said, knowing the commit ID something is fixed in, so that the PM can track what build it emerges in is useful.
The difference is that the Jira ticket is for everyone involved in a project (business analyst, UI designer, QA, support, DBA), while commit messages are written with developers being almost exclusive audience. PRJ-123 might explain why an end user might need it, but the commit message explains why the change (diff) is the way that it is. The ticket answers requirements-level questions, the commit message answers code-level questions. Commit messages are useful both during the review and when a future maintainer is reading the code.
> Additionally, if a change requires multiple commits, you don't want to be repeating the justifications for the entire feature in every commit message. It's redundant. But the commits will all be tied together by the ticket reference in the commit message.
Different commits do different things, so require different justifications. Here's a fictional example to demonstrate:
First commit:
[PRJ-123] Server: extract class Foo
In the next commit, we're going to need to re-use the foo logic from
class Bar. Extract new class Foo from Bar to make it available for
re-use.
Second commit on the same ticket
[PRJ-123] Server: use Foo in Baz
The users of BazClient need to be able to see foo information in the
baz dialog. Include Foo in the data sent by class Baz in the server.
Side note: the user might not even know that they are looking at Foo and Baz, it might be called something else in the UI they are shown. Whether or not this needs to be included in the commit message depends on the situation.
And later in a commit fixing a bug:
[PRJ-456] Server: check ID for null in Foo
When class Foo was extracted from Bar in commit deadbeef ([PRJ-123]
Server: extract class Foo, 2026-06-06), a null check for the field
ID got lost by accident.
Check the field ID for null in class Foo to avoid a
NullPointerException when a foo event is sent to Baz.
Personal preference I guess, but to me all of those commit messages are way too wordy. I'd probably have:
[PRJ-123] Refactor Foo out from Bar
[PRJ-123] Include Foo data in BazClient
[PRJ-456] Null-guard on Foo ID to avoid data loss
Bug introduced in commit deadbeef
And then in PRJ-456, I'd also have the comment about bug introduced in commit deadbeef, and link the two JIRAs if it was significant, or just mention it in a comment for a minor fix.
For me personally, nothing else in your commit messages adds value that can't be seen trivially from glancing at the changes.
Git is more robust than Jira. Git log is accessible offline. Jira descriptions exist only as long as people managing the Jira instance are competent and are migrating the necessary data correctly when migrations are needed. Even migrations from one Jira instance to another (e.g. when companies get acquired and two Jira servers get merged) can be extremely brittle.
It's fair that maybe such simple trivial changes don't deserve such a wordy commit message. But these are just fictional examples that I came up with on the spot. Refactorings, new features, and bugfixes can all have various levels of complexity.
A good commit message helps answer the "why?" questions first and foremost. If a diff is fairly large, pointing out the most important change can be useful. Explanations for non-trivial dataflow can sometimes not make sense in separate documentation, but still be relevant in a commit message.
Interesting to see somebody argue out in the wild for what I have been subjected to in the past and have long considered absolute worst practice.
It may be that my perspective is different because my work tends to be in "hard" foundational software (think OS components and programming language tool chains). It's not that customer requirements aren't a thing at all in that kind of work, but they tend to be far removed from the day-to-day and instead, mechanical sympathy rules supreme.
Commit messages need to focus on the software, not on the trappings of the process by which it evolves. Links to tickets can provide helpful context especially for bug fixes, but they belong in the commit message footer.
Your last paragraph is absolutely an anti-pattern at least in this work. If the implementation of a new feature is split over multiple changes, then surely there is something different and important to say about each of those changes. Does your split even make sense otherwise?
Exactly. The commit message is supposed to be for the future developer, not to generate changelog.
And the main case when that developer reads the commit message is when he doesn't understand _why_ that commit exists. Not what it changes, but what is the purpose of certain lines. So he runs "blame", sees commits, the original developers are not with the company anymore, the old JIRA may not exist too, and the only hint is the commit message.
This, along with the "successful git branching model", are symptoms of the fact that devs overwhelmed with the flexibility of git and look to other people to define standards for them because they that lack the experience to do so for their own requirements.
Actually, this is also similar to classic OOP, where people use a contrived method of structuring their code.
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”.
You just made me realize why I've always considered 'chore' the most ambiguous type. In addition to being loosely defined ("transparent change with zero functionnal impact"?), this one is indeed a word related to emotion. No wonder it has a more subjective meaning than 'fix' or 'feat'.
This is why I never use it and almost always pick 'feat' to please the linter. Because I can't help considering that any change worth committing is improving the quality of the code in one way or the other, and thus a feature.
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.
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".
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.
if IDE supports converting them into clickable links, then scrolling through a log in its Git integration (kinda like `git log --oneline`) will be a convenient list of links to issues. If the commit messages are good, you just skip over the Jira issue/ticket key/ID. If what you want is to see the requirements of a feature or steps to reproduce of a bug or some other context for the ticket, then a clickable link is very convenient. Of course, sometimes it does make sense to include some of that information in the commit message as well.
When working in big teams, it can be very hard to increase the usefulness of commit messages. On the other hand, enforcing inclusion of a Jira issue key in commit messages is easy to implement. Relying on issue tracker descriptions can be a difficult proposition as well. Quality of individual ticket descriptions can be low; depending on how responsibility for maintenance is handled, the bug tracker migrations can sometimes be handled improperly and information can be more easily lost than in a Git log.
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.
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.
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 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.
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.
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.
I think you’re the first person in this comment section to mention this. Git has a structure for machine-readable structured data. Put it there, not in free text fields for humans.
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.
It's only a convention around commits suggesting to prefix them with certain short words, there's nothing stopping anyone from including issue numbers.
All ours at work do: "feat[component]: DEV-1234: description"
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.
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 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 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.
Why does that need to go in the title though? Just put some magic in the commit bodies, if you want to do versioning in that weird way. Then you aren't restricted to a single word either.
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.
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 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.
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.
Inverting the order actually addresses my primary annoyance: what is a feature?!
> refactor(core): Update webmcp support to use document.modelContext
As the author points out, the line between a fix, an improvement, and general clean-up is blurry and dividing each semantic change into its own commit (and possibly squashed later anyway) is just creating work for no one's benefit.
I think Conventional Commits are just an artifact of trying to automate SemVer rather than solving any of the other problems directly. I don't think changelogs should be automated anyway - I can `git log` that if I want a list. A changelog is an opportunity to communicate to a wider audience what is actually going on under the hood.
“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.
He confuses changelog with release notes. Doesnt know how to name commits and probably doesnt know how to name symbols either. Skill issue and he’s sad, now in public. Move on…
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.
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.
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.
You never need to write "fix", or "prevent" if you write a good message. Nobody says "fixed the car by changing the flat tire" or "Go prevent engine wear by getting an oil change today. You say "Change the flat tire", or "Change the oil".
You can do the same when you write commit messages. "Wrap user and account update in a transaction" - "Delete temp files after use".
I disagree. I think the commit description should be "stop the engine wear", not "change the oil". I much prefer commit messages describing why you did the changes, because the explanation of what you did is already there - the code diff itself.
Whatever describes the change better. Sometimes the issue is easier to describe "fix: car steers in slalom". Where the solution would have been subtle interaction between 3 different components that only occurs in 3rd gear.
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).
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.
All the items being discussed are useful things to think about and cover in the commit message. Certainly if after reading a commit message I do not know what was intended (eg. “is this a refactor that is not intended to change behaviour or not?”) then the commit message is missing something. What I object to is overloading all of this into the first line. The subject should be reserved for the most relevant information and is limited in length. Forcing committers to collapse a bunch of metadata into it makes it less useful for that purpose.
Keep a Changelog[0] maintainer here, weirdly seeing this while deep into work on way overdue 2.0 "release"[1], which should be out very soon.
I've had to contend with Conventional Commits both in the OSS world and at work as it proliferated from what seemed to me like robotic adoption by folks who were even loosely associated with the Angular ecosystem (remember that?).
I've always had a stance with KAC that folks trying to automate changelog creation (prior to LLM rise, mind you) were focusing on the wrong thing. I still think there's a fundamental difference in focus between what you write in a git commit and what you present in a changelog.
I know there are fundamental philosophical differences for folks who were used to HISTORY vs. NEWS vs. CHANGELOG but with the growing adoption of KAC-like CHANGELOG.md files and Release Notes (often not synonymous) I think we're thankfully past the weird era were maintainers dumped raw git log ranges between two tags and called that a changelog. I'm sure some still do it. But that's what Conventional Commits tries to replicate.
What's really odd to me is that this assumes (broadly) that every single commit in a repository is relevant to the eventual version release changelog (or release notes). Even if you assume some CC types get filtered and deprioritized from generated changelogs by some tools, it's still a huge miss on what communicating about a release typically means: these change likely matter to you as a package dependent or direct user, while others were omitted for good reason.
I'm trying to articulate that much more clearly in KAC 2.0 because there's a fundamental paradigm shift when a robot can now analyze recent work (yours or theirs) and craft changelog entries that appropriately shift the audience perspective from "git message for me/us in the future to understand this change" to "changelog entry for you/them to know what this group of changes means".
I totally agree with the sentiment behind this, so much so that I also made my own standard a while ago, https://commits-with-character.org/ an incredibly light addition to the Git Book guidelines, and also gives more priority to scope. It’s been working really well for me in my small projects.
Wait. i am already struggling with 50 columns for the title, now i have add this `<type>[scope]:` bloat to it? How are these people doing both "Conventional Commits" and 50-72 at the same time?
Broken promise 1 (Automatically generating CHANGELOGs) is spot on, especially in a monorepo with multiple released artifacts. A single commit could be a breaking change in one package and refactor in another. But the changelog tools see one commit and include it in both changelogs.
Another issue is that once the commit lands on trunk, you can’t revise the entry without editing history. You have to remember to fix it after the changelog is generated.
The issue with all of these schemes is less about the format and more about the semantics itself. What are all the actions that can be done to a codebase and what is a controlled vocabulary that encapsulates those? Then it doesn’t matter what system you use.
I spent some time recently coming to the conclusion that I did not prefer CC, but wanting some reliable structure. In the end, I found I was coming up with convoluted schemes that were getting in the way of actually solving my real problems and just settled on the tried and true:
“When applied this commit will...”
- Add <functionality>
- Update <existing>
- Refactor <while keeping same boundary behavior>
- Remove <some subsystem or functionality>
- Cleanup <documentation or style>
I don’t consider this to be a complete taxonomy, but it does let me get on with my day and covers most things, especially when combined with thoughtful commit messages.
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.
Making an opinionated absolute statement about something that's widely used and argued about isn't even logical. If nobody got any benefit, it wouldn't be a thing.
The CC standard may not be for everyone, but having some convention is often helpful. git log --pretty=oneline of structured format gives you broad filtering that's useful. Just writing like a human doesn't give you that ability and you're forced to read every line.
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 stick with Conventional Commits as a standardised way for communicating changes. Most contributions in the form of open PRs are squashed before merging into base branches. A team member can commit as personally wished in the feature branch. I still use CC for my own sanity and I’m very glad I do comparatively to what usually find in others feature branch commit histories.
Without standards most developers I’ve seen are very careless.
I generally work with changesets to curate changes at the time of contribution in accordance to semantic versioning.
Conventional Commit messages have big https://goomics.net/361 energy. Or at least the mechanisms that repositories use to programmatically enforce their use.
(I can't believe nobody has pointed this out yet.)
The essay gives a bunch of reasons to drop the "type" altogether and just use "<optional scope>" as prefix. The type either doesn't really mean anything or is redundant when writing commit headlines as English sentences. In a message like "Prevent thing from happening" the verb "prevent" is already basically a synonym for "fix". Similarly "Add" or "Support" likely implies "feat"/"feature".
To some extent the "type" is simply about trying to limit/standardize the number of possible "verbs" to start a commit headline with, in which case Conventional Commits made the mistake of mixing verbs and nouns (fix and refactor are verbs but feature and chore are nouns) and adding distracting punctuation where English prefers none between the Verb and its direct object in a "Verb the thing" sentence. "Verb: the thing" only ever really looks awkward.
But also do we really want to limit the possible number of verbs that a headline sentence can start with when making commits? "Fix" and "Prevent" may often act like synonyms but there are connotative differences. In some cases "Prevent" may be a shorter way to explain why something needed to be fixed in a headline because "prevent" also says "stop a thing from happening that wasn't supposed to happen" whereas "fix" alone may not yield that extra context. The top line of a commit should be a short and sweet headline and sometimes the cleanest way to do that is to use the full gamut of English verbs at your disposal to tell the right story as quickly as possible.
In my experience both are more often in noun form with an article ("a fix" and "a refactor") because they are both sort of awkward alone. But sure I can appreciate that's probably how we got the set of words that we did that they were all picked as nouns and only in juxtaposition does it become more obvious to me that I think it might have been better to have picked just verbs. I can see the sorts of thoughts that led to "noun: verb the object" as a "good" headline format, especially when the "noun:" is considered the important part of the headline. But only before realizing it is generally redundant between "noun" and "verb" and "noun:" might not really be all that important (as the article points out flaws in).
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 is the kind of thing where the extent to which people get worked up over it far exceeds the benefit of actually doing so.
Is it theoretically possible that people can write good commit messages without a framework? Yes. Does that work out in practice across entire teams? No. Any kind of a convention for commit messages is an improvement.
Beyond that, type > scope vs scope > type or whatever is splitting hairs. The juice of that debate is not worth the squeeze.
As a reviewer, I love type first because it sets expectations for what I'm going to look at. Similar if I'm bisecting or doing other history operations.
I don't do automated changelogs or versioning but it also makes it faster for me to do so.
I really dislike focusing on issue ids. I only want to jump to another tool if I need more information, so put it in the footer for after I've read what is there, like a front page news article giving you the option to go to the back to read more. Worst case that I've seen is people that think the Issue ID is all you need.
I feel +/- line counts alone give a good sense of whether something is a fix, a refactor, new feature/component.
After that it’s great to know where is primarily intended to be impacted.
Then look for what the change is and does.
There are some good ideas in this proposal but the author is creating a false dichotomy by saying the current standard should be scrapped. Two things can coexist and both be good. I hope the author reconsiders their approach in their future promotion of their idea.
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.)
I personally like it for one of my work projects. Its the only one we use it on. Its a repo with the android and iOS app. I like the conventional commits because when doing releases, I can look between two tags and pick out what I need to put in the "What's new in this release" section. I try to not just do the normal, "bug fixes and various improvements," in that section, but what we actually did. Also helping make clear what went into a release branch/what needs to be cherry picked into a release branch. I also don't automate the generation of the "Whats new" section. I just take a look at all the commits between tags.
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 like using conventional commits but I’ve often wondered if some sort of tagging/labeling using git-notes wouldn’t be better: https://git-scm.com/docs/git-notes
I’m just unsure that the short title is the ideal place to put this kind of tagging info: the kind of fix, and optionally, the relevant component(s). I find sometimes that can take up the majority of the title.
A forge could consume the git-notes and decorate a commit/pr accordingly. Heck, GitHub PRs already have a labeling system in place, just have to add some glue.
I agree with the sentiments -- knowing the scope of a change is more essential, in most cases, than knowing whether the change was a "fix" or a "feature" -- but much of the scope in a project can be gleaned from the files which were touched. So the use case of, "i need to quickly at a glance determine what commits touched what parts of the project" can be answered with some variation on
I used and use Conventional Commits in private and professional projects and I think they have a place.
That being said, when I finally committed to using them something in me broke. Most of my career work was double faced. One face to the customer where you need to keep Tatemae under all circumstances (UI, Tickets, etc.). The other was the code and commit messages where you still kept your professionalism but you could be open and speak the language of your peers.
This time is over, maybe for good, but a tiny part of me misses it.
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.
From my own experience in big tech and various OSS things, the crux of this piece rests on this whole scope not being focal point misses that in general the other practice is making sure PRs have limited scope in general so it's marginalized, i.e. reducing blast radius or too big of a change at once by design is implied.
I've been a developer for 40 years. Used VC since rcs. If only people had such pedantry for the actual code, the world would be a better place. I look at the author way more than I read a commit message, next the date and then the code. Never much else.
Conventional commits is one of the weirder cargo-culty things we do in this industry. I do take issue with this, though:
> Automatically determining a semantic version bump (based on the types of commits landed): This sounds nice, but the realities of software engineering often interfere significantly with the viability of accurately accomplishing this... imagine a situation where the breaking change you introduced was actually so breaking that you have to revert it... maybe the breakage is subtle and you don’t realise a change is a breaking change when you make the change. Only in retrospect realise that it’s breaking. You will incorrectly increment a minor/patch version when a major version bump is necessary...say you later add a commit which, in composition with a previously breaking commit, results in a diff which is not breaking. Similar to the revert situation, tooling would incorrectly identify a breaking change.
This is a problem with Semver, not conventional commits. You're liable to do this regardless of how your commits are formatted, which is one of several reasons why conventional commits are silly. But in this case, Semver itself drew semantic lines that aren't clear, and are easily broken.
the article mentions three types of stakeholders: contributors, debuggers and incident responders. it entirely fails to mentions consumers, who mostly care about backwards compatibility of changes, and thus about the type of a change. once the type is established, e.g. a change is breakimg, the consumer next cares about the scope to make downstream adjustments.
the part about broken promises regarding breaking changes is _kind of_ fair, but only assuming tooling isn't able to track reverts. accidental breakages occure with every approach and better to have an approximation than no information at all.
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.
Thank you for the thorough write up! I just thought about this today and needed the set of arguments and examples you brought forward. Especially the pointers to NixOS et.al. were informative. Thanks!
I have never once considered conventional commits to be about human understanding, but more about automation (release notes, changelogs, and workflows).
The commit description and the pull request are for humans.
Why not both? Scope is definitely important. But type is also important:
- prioritization: bugfix > docs
- visibility: are we spending more time on bug fixes or features?
Also, we let AI write the code, are we STILL writing commit messages by hand??
Commits should have no information in them. Teams should be aligned on the design of their software, and all the information about that software should be apparent from its source code.
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.
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 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.
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"
You know what lacks focus? This whole article. Oh, and also individual styles of commit messages. You know what’s a waste of everyone’s time when you’re building technology in 2026? How to write and summarize what you’re work is doing.
Conventional commits doesn’t make a promise, it’s a specification. Words have power and meaning, this viewpoint is about more than a spec, it’s about the popularity and relevance that they clearly despise.
Conventional commits are like BEM syntax for CSS, it works if you pay attention. It’s structure around what developers do, which thoughtful limits. What is the problem with that? Is it the only way? No. But to say it’s encouraging the “wrong things” pshhhh
This author’s take is dog water for coders who yearn to be controversial and (clearly) focus on the wrong things.
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.
I'm not getting why "scope" gets any priority at all. Are filenames not attached to a commit for those exceedingly rare cases where you're looking for which files are thrashing?
Also not getting the downvotes. It's not a rhetorical question; it's a question looking for an answer. If somebody could explain why "Scope" gets should get precious space in the title of a commit, I'd be grateful. It seems inconsistent with the reasoning used to remove other pieces of information. If "feature request" or "bug fix" doesn't make it into the commit title because it's usually apparent from the description, then surely the same is true for "scope".
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.
Defined structure does not constitute quality. A commit message can be loosely structured, but be very insightful and good at communicating the nature of the change. On the flip side, one can make a very structured but confusing or non-informative commit message. I generally tend to agree with the author, conventional commits do not solve the core issue of the poor commit messages problem.
Conventional commits made it easier to generate changelogs and automate semantic version bumps. I suppose LLMs can usually do that the right way with looser structure, but in the before times it made a lot more sense, and even now is much less ambiguous
Both of these things are discussed in the article. (changelogs and semver)
They're hand-waved away by saying the changelogs are bad and the semver isn't always accurate. While I mostly agree with, that doesn't mean they don't provide _some_ value. You get categorized changelogs (even if the messages are technical) and semver that's generally correct. The alternative of good changelogs and perfect semver isn't free.
Auto-generated changelogs from commit messages are bad, no matter if the commit messages follow some structure.
I suppose it is a significant downside that you could get misled into thinking you can autogenerate a changelog from commit names.
why is "solving" the issue somehow the bar? software engineering has more practices rooted in psychology than engineering, its a moving and ambiguous target. Using conventional commits gives you a framework and mechanism that undoubtedly improves contribution semantics.
Why undoubtedly?
In what context does wasting your first characters on fix vs feat matter?
PRs are going to have an explanation that has way more detail than necessary to figure that out quickly.
One lines tend to be (for me) in a situation where the difference is immaterial. If I am rapid firing through history I need to know what you did not why you did it.
Again I am not claiming that these are bad or even that they aren't good.
I am specifically disagreeing that any change is automatically good, that isn't true.
> Using conventional commits gives you a framework and mechanism that undoubtedly improves contribution semantics.
I do not want to contribute to a project using conventional commits. I have consistently found, that I am unable to decide what the "type" of a commit even is and I feel unnaturally caged in into how I would split up commits, by having them be restricted to types (it doesn't help that the conventional commits I've seen appear to decide the type by fair dice roll).
Discouraging contributions does not "undoubtedly improve contribution semantics".
Sounds like a you problem because I never had a issue taking 30 seconds to read a contributors guide.
It’s the linting argument all over again. I don’t give a shit what the style is. I give a shit that it’s consistent. Form whatever opinion you want about how you want to format your code, structure commit messages etc. I don’t really care, if you want to start every commit with “poop(fix): pooper my commit message”, as long as you’re consistent about it and enforce it programmatically you have my emphatic support
This comment assumes you are picking between a conventional commit message or something better. But the reality is you are almost always picking between a conventional commit and Nothing.
That is only true of semantically equivalent things.
Tabs vs spaces don't matter they are equivalent.
But consistency is only better when it is an improvement.
It is fundamentally important that convential commit is better for adopting it to be an improvement.
After all in your example wasting the first four characters of your commits with poop would objectively reduce the quality of your commit history, whether or not it was consistent.
> Tabs vs spaces don't matter they are equivalent.
Just to nitpick (because what else is this thread about? :))
They aren't equivalent! Tabs carry more semantic information than spaces. 1 Tab character == 1 Level of nesting
Space-based systems _can_ provide the equivalent semantic information if they are 100% consistent.
...but part of the argument in favor of spaces is that they allow an escape hatch of the strict indentation in order to allow pleasing visual alignments.
I don't think it's reasonable to judge Conventional Commits on something it doesn't claim to do.
I can't see any suggestion on the CC site [^1] that it "solve[s] the core issue of the poor commit messages problem."
Rather, it's explicitly described as "a specification for adding human and machine readable meaning to commit messages."
I'd say it accomplishes that modest goal.
[^1]: https://www.conventionalcommits.org/en/v1.0.0/
I end up thinking that conventional commits is a good idea because you can make tooling force people to at least put one iota of thought into what goes in a commit message. I've had to review so many commits with the subject "small fix" that was not in fact a small fix.
So now you'll get a lot of "fix: small", heh.
Who reads commit messages anyway?
Maybe more people if the contract is that it’s how you get your work into the release notes?
I work with legacy code and am regularly reading commit messages from 10-15 years ago while figuring out what was going on several teams past. It's also why I'm against squash-merges, there have been plenty of times a commit was in the middle of a chain of commits and the helpful context would have been erased if we had squashes in svn.
Commit messages are usually more useful than code comments. For one thing they change when the code changes, so they are much less likely to lie.
I don’t have a horse in the race, but the OP objections ring hollow to me.
- scope is important: true, but isn’t that derivable from the commit contents? An important sanity check on a diff is to look at the paths touched. (A “test” diff should not modify prod auth code.) but if you want to see this from —oneline, sure, I think feat(auth): is better than feat:
- wrong audience: I don’t agree. feat commits _should_ actually describe the product-facing changes. You _should_ curate a nice stack with your no-op refactor changes first, then your small new feature change atop. This is the most helpful thing to include in a diff comment. You should put anything technical in comments so they are not lost, “why I chose algorithm X” belongs in a comment or DECISIONS.md. These are all tedious things that only psychos bother doing in a commit history at a fast moving company, but on OSS projects I think it’s much more important to stash context in the commit messages.
Sidenote: Although JSON is very common, I argue EDN is the best data format out there.
Curious: what are the primary advantages you see?
Not GP but I enjoyed reading through some details of EDN here, I hadn't studied it before: https://edn-format.dev/
Yeah, I looked through the GitHub. I've used Clojure before so it seems pretty easy to pick up.
I'm not yolkedgeek but I can give my own answer: EDN has tags. Tags start with `#` and are followed by a symbol (which is a lot like an identifier except that a lot of punctuation is allowed in symbols, because EDN derives from Lisp syntax rules). The `/` character is used for namespacing, and a user-defined tag must use a namespace. The tag meaning is application-defined, but there are a couple standard tags with well-defined meanings:
#inst "1985-04-12T23:20:50.52Z" = an instant / timestamp in RFC 3339 format
#uuid "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" = a GUID/UUID
More tags could be defined by the standard later, because the entire unprefixed namespace is reserved. But just having a well-defined way to represent timestamps and UUIDs is an immense win over JSON, where you have to somehow know (based on what you were expecting to receive) that this string should be parsed as a timestamp or a GUID.
Also, user-defined tags will often be used to represent a class:
#myapp/Person {:first "Fred" :last "Mertz"}
Again, no need to know (based on what you were expecting) that this particular object is an instance of Person; the data transfer format tells you what class it is. JSON has to add a field, and what field it is will vary from application to application so it's usually not possible to write a universal parser. One server might generate { "__type": "Person", "first": "Fred", "last": "Mertz } while another one does { "$$class": "Person", "first": "Fred", "last": "Mertz }, for example.
EDN also has syntax defined for sets, but that's a smaller win over JSON, because it's not often necessary to declare that something is a set. Still, there are times it's helpful; it's certainly not a bad thing to have a set syntax.
Also, EDN has comments built in to the system. Two kinds, one line-based comment (useful for actual comments, e.g. when you use EDN as a config format), and one that comments out the next thing in the file (useful for temporarily commenting out an entire section with a single token, or for removing ONE item temporarily from a list that's all on the same line so line-based comments are difficult). Because Douglas Crockford didn't envision JSON as being used for config, he forbade comments in JSON, and people have been coming up with competing proposals for putting comments back in ever since. (Thankfully, nearly all the proposals interoperate, because all of them sensibly use Javascript comment syntax, so it doesn't matter if the file is JSONC or HuJSON or JSON5, the comment syntax is the same).
But the biggest win for EDN is tags, which can convey type information outside the data structure. JSON has to use something inside the data structure to convey type information, and there's always that small chance that the name chosen (__type or $$class or whatever) will collide with a property of the actual object that was supposed to be serialized.
I get tags and atoms. It seems like the problem with class serialization is somewhat arbitrary though. It seems like both sides need the object schema ahead of time, in which case the schema can flag how it sdould be IDd / tagged.
I also wonder if atoms can be reduced for low-bandwidth transmission. Naïvly, you could just prepend a lookup table for multiple-use atoms.
I guess it seems more like niche, additional features when GGP seemed to be claiming a big step up.
I haven't used EDN, but I know YAML has an equivalent feature, and that had been a security issue in some instances because it deserialized into objects the system wasn't expecting. Perhaps their deserializer had learned from that doesn't have that issue?
Haven't used EDN myself but from a read through the docs, I'm pretty sure that on user tags, the deserializer just says "Here's the tag, and here's the object it was tagging" and lets the consuming code decide what to do with the tag. (And on canonical tags like dates and GUIDs, there's no security risk to deserializing them as the recipient language's version of timestamps and UUIDs).
Actually, https://github.com/edn-format/edn says "It is envisioned that a reader implementation will allow clients to register handlers for specific tags. Upon encountering a tag, the reader will first read the next element (which may itself be or comprise other tagged elements), then pass the result to the corresponding handler for further interpretation, and the result of the handler will be the data value yielded by the tag + tagged element, i.e. reading a tag and tagged element yields one value. This value is the value to be returned to the program and is not further interpreted as edn data by the reader."
So if the client is specifying the handlers, then it's up to the client's handler implementation to sanitize the incoming data before instantiating the objects. And since the client supplies the list of handlers, the only tags that will be handled are ones the client was expecting. Assuming sanitizing the incoming data before instantiating objects is done correctly, I don't see any way for that to become a security issue.
I’m all for standardization but you could just use this argument to keep any suboptimal status quo in place. XML is good enough and a standard. SOAP is good enough and a standard. etc.
The claim is that Conventional Commits are good enough and standardized enough that having another structure isn’t really worth it. But “worth it” is subjective. I’d say that if you are making commits and reading PRs every work day, and the conventional commits format causes a little bit of friction, that friction can add up. Having another option other than seeing conventional commits as a law of nature gives options for teams who prefer it. (Most teams aren’t generating changelogs anyway.)
The new structure needs to be "better enough" that it overcomes the built-in deficits of the older structure, and it can't introduce so many new problems that make it a net negative.
JSON was definitely a huge improvement in simplicity and readability compared to XML for many contexts. Similarly REST a much better option than SOAP (and all of these are examples of the general over-engineered, design-by-committee architectures that came out of the late 90s/early 00s - see also the original EJB spec - before a larger trend towards simplicity and ease of use won out).
But it this case, a lot of the differences just feel like potayto/potahto, i.e. minor stylistic preferences. And I have been in jobs where more than 50% of my time was doing code reviews, and while often there were e.g. some linter rules or whatever that I found suboptimal, it was a lot easier to just go with it than waste the energy to have the battle over why I think for loops are actually OK.
I don't need a standard for this. This is just noise. There are some people who have some sort of mental ailment that makes them obsessively want to introduce "structure" "scheme" "patterns" where it is just innately nonsense. You do you, but stop trying to force it on people.
Reminds me of the "scrum master" adjacent folks who could never cut it writing code and then branched into all kinds of things like "Git Flow" when having never understood Git to begin with. Peak bikeshed territory.
Reminds me of a place I worked at where a "naming committee" had to approve variable names. And no, you could not use "i" as an index in a one-line loop.
i and j etc is bad though, but for a different reason than usually claimed. it's suboptimal because it's hard to search for. just use ii, jj, kk, etc
\<i\>
If you need to search for a variable named i - you should have named it something else (and no, jj is NOT an improvement in that case).
One letter variables are supposed to be used in scopes that fit on the screen completely. You might as well search for "for"
TL; DR: it's on purpose.
Also the fact that every search function since the dawn of interactive computing can search for whole words only (like -w in grep or C-w in emacs).
> One letter variables are supposed to be used in scopes that fit on the screen completely.
Exactly, and ideally in less space than that. If you have something like:
There is no point in using a "descriptive" name for the index. It's completely obvious what's going on. Anything more verbose would just hamper readability.
Introducing JSON scoped comments, far superior to JSON conventional comments. People who use those are our rivals.
> Douglas Crawford
Crockford.
Some programmers prefer 2 spaces, some programmers prefer 4, why don't we compromise and pick a number between 2 and 4?
hence tabs. just configure your display for the width you like.
though I do wish more editors had some kind of "ignore the spacing, display it semantically like [this]" and just let you insert whatever you wanted, converted to whatever is nearby, and didn't touch lines you didn't create. there's no reason to even have the debate or care about inconsistencies, you can essentially always* convert between them losslessly in terms of behavior.
The next iteration is "smart tabs", where indents are stored as spaces in files for consistency, but when using an editor it recognizes that something special is going on, and offers you a tab-like experience.
which they kinda already do, yea. I just want it to be stronger, and to correct indentation that doesn't follow your formatting rules (which I have not seen / is not widespread). kinda like a `gofmt` overlay on a file, rather than modifying the file directly.
as a bonus, this could also make `goto fail;` errors more obvious.
Given a choice between (spaces) and (mix of tabs and spaces) -- these being the only two options IRL -- it's not hard to see why spaces won.
π?
> 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 big deal is not that scope is more important then type, the big deal is that natural language allows you to formulate things to emphasize whatever you consider important, and by forcing everything into a specific format this information is lost. There's a reason we have formats like markdown and plaintext, not just JSON.
Conventional Commits still have a free-form description section. The structure just introduces some standardized elements - and this is common in all types of written communication. Books have tables of contents, chapters have titles, letters have salutations, etc. etc.
Great perspective! As a sidenote, I really like json5 for everything that would be needed for a human to read and it has great support everywhere. It fixes so many of JSONs shortcomings like comments.
Edit: forgot the link if anyone’s interested https://json5.org/
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.
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?
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.
Absolutely not. Commit messages should never be automatically passed through to the end-customer. I also worked in a place that tried it once and it was a disaster. Sure, a list of commit messages can be a useful start as a list of things that might want to be put in the release notes, but very rarely is the developer the right person to be explaining those changes to the end user.
If a developer is being asked to do that, it's a good sign that the PM isn't doing their job properly.
They did not say generated release notes are useful if you care so little you would write no release notes without them however.
You can have a writer re-write them into acceptable release notes. It gives them a good and accurate starting point.
Closed issues are a better starting point in my experience.
That's right, but with AI help + some hallucination you can get nice looking release notes out of the worst mess of commits.
Pretty much everywhere I've worked recently enforces some kind of jira ticket number in the PR title
This is the way we did it when we used JIRA.
For GH issues you can always navigate back to the PR discussion (which should have linked issues and other pointers in it) from the commit.
Of course when we switched to GH issues, we largely abandoned JIRA and years later the instance got turned off and deleted. Now all those JIRA tags are entirely useless.
IMO that actually argues for tight coupling between your issue tracker and your git repo. And what you really want is portability (which I don't see how you get other than with tight coupling). Ideally there would be open standardized formats, but as it is, github is the 800# gorilla that defines the format and as long as gitlab and other clones can slurp in github project metadata (or at least PRs) then that effectively gets you closer.
But any way... Fixed, immutable pointers to an Atlassian product that you might not be using in 5 years is not a good policy. I'd sooner accept the policy that the git commits needed to stand entirely on their own and all the information about the "why" of the change needed to be baked into the git commit or the comments in the source (I think that fails, though, since everyone is overly terse in git commits and summarizes issues and loses information--and the back-and-forth dialog in a PR discussion is useful because it contains more than just one person's voice summarizing the reason for the change).
> we largely abandoned JIRA and years later the instance got turned off and deleted
Sorry to be nitpicky, but why did you abandon a tool that contained a lot of valuable knowledge? That's not the fault of GH nor JIRA, that's your fault. At least you'd back up descriptions + comments from these JIRA sources.
Like many tools defending their moats, tools like Jira don’t make it easy to get one’s data out.
That isn't true though. It's very easy to export your data from JIRA. From your board, go to the List tab, filter the items to whatever you want, and then click ... and you can export the data in various different formats. Exporting as XML dumps everything.
I my case it was a different system that got bought out by (I won't say but your guess is likely correct) and the new license terms were unacceptable
You can trivially export your data from JIRA. If the parent experienced a situation where valuable information was lost because the instance was deactivated, that's not JIRA's fault.
The team that makes the decision to change issue management systems and not to back up the data is rarely the team most affected by that decision.
I didn't abandon it, it was run by a different team, and we were one consumer of it. When the organization switched from Jira to GH issues the Jira was kept running for years, but nobody got the information into GH issues. Eventually the Jira was shut down, certainly by the time the company got acquired.
> Of course when we switched to GH issues, we largely abandoned JIRA and years later the instance got turned off and deleted. Now all those JIRA tags are entirely useless.
We did Bugzilla -> FogBugz -> Jira. Almost all the data was lost every time, no one bothered with migration except for the maintenance project. Worse, even on Jira we lose cases as teams end and hand off the code, and the Jira project is closed so no one else can access it.
We've also done cvs -> svn -> git. All the commits have survived migration.
I do keep including cases in the commits messages, if nothing else it'll help link things together in the future, but never rely on them for context a future maintainer might need.
> Similarly "bug", "fix" or "feature" adds no useful value.
If you're not using/tied to an issue tracker, embedding tags like these in git gives you some basic metrics.
> 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.
The "why" is THE thing that needs to go in the git commit message. Capturing "why" is the entire point of that message and slapping a link to some external (and eventually absent) resource is not a good substitute.
It is a good substitute.
1. Usually the commit message is often too short to capture the "why" adequately. 2. It is very beneficial to capture the why in one single source of truth, and that usually is not the Git commit message in a business context. Hate on Jira all you want, but if you capture the "why" there, you can add comments, view history, add rich context, link dependencies, add rich context, etc. Can't do that in a Git commit message.
You can put that in the body of the commit message, not everything has to go in the subject line.
My ire is more directed at github PRs than Jira... but the same basic idea applies. You want a single source of truth and you want that as close to the origin (the code) as possible. Your history, dependencies, etc. are all in git already and can be highlighted there if appropriate. For general comments, git notes covers that.
Business (ie. $work) will dictate whatever it wants and that is what get used but for anything I personally have control over, everything goes in the repo itself to prevent platform lock-in. For example, github's been going downhilll lately but all those projects with their history in PRs, etc. now needs to exfiltrate all that data somehow.
Jira contains discussion and requirements. It can meander for months before the right action is chosen. It can be important to have background, but it replaces the mailing list discussion that led up to the change, it does not replace the commit message.
The commit message is writen in retrospect and is written for someone with the code in front of them to explain why this change was made, and why it was done in this particular way.
If your commit message is too short then than is your problem right there. The easy fix is you taking five seconds out of your busy day to save an hour for you readers.
Have you seen how commit messages are written for git itself, or for the Linux kernel? Let me help you by linking the currently latest commit in the github mirror of git, it is not chosen to be particularly good or bad but is pretty representative of how git developers write commit messages: https://github.com/git/git/commit/b809304101
As you can see, without knowing much of the specifics of the code, we can get an idea why this change was made the way it was. There is a certain art to writing short and concise commit messages, but the same is true for code itself. Some, but comparably very little, practice is required.
I find bug trackers and source control fad change several times over the life of my code. A number from a ticket system we no longer use is not helpful.
But a number from a ticket system you are using is helpful and vastly more log messages will be read during the time when it’s active than after it’s been retired/replaced.
The switch was too recent in my case, I'm still seeing many numbers from the old system that I can't look up.
You should shout at your project managers then.
The data in the ticket system should be considered important as it's the primary interface through which developers, QA and design share information.
Respectfully, I disagree. A good commit message to me is something like:
[PRJ-123] Changed blah to foo
Blah didn't handle the wangle flange properly in some cases, foo is a better fit for customer requirements.
The "why" that justifies the change, is already contained in the JIRA ticket PRJ-123 and explains exactly what the customer requirement was that necessitated the change. It will almost certainly contain a lot of detail that isn't relevant to the commit message, because that isn't the place to be documenting customer requirements, and probably relates to a number of other tickets. Perhaps the code itself might have a comment explaining the code change, if it's a non-obvious implementation, but otherwise the ticket is the best place for that information.
Additionally, if a change requires multiple commits, you don't want to be repeating the justifications for the entire feature in every commit message. It's redundant. But the commits will all be tied together by the ticket reference in the commit message.
Hah, maybe its the difference between why as in "this addresses problem X" and why as in "because those jerks in pre-sales sold another imaginary product"
I think the commit ought to describe the purpose of the change in terms of its result for the software's intended use. Feel free to hide the business/political drama behind a ticket number.
This gets down to a more fundamental tension. Are commit messages to communicate between developers? To communicate from developer to consumer? Or some kind of project manager golem? In practice, it is usually some constantly wandering attempt to be a blend of these.
The last part is easy to answer. Commit messages are solely for developers IMHO. The communication between developer and customer / product manager should be via the ticket system.
That said, knowing the commit ID something is fixed in, so that the PM can track what build it emerges in is useful.
3 years later. You are working on some old project that apparently is erroring.
Through a git bisect, you find a commit that references JIRA, though your company uses Linear.
You sigh, and start reading the diff.
(Adapted from real life events)
That's where something like Fossil is nice, because the tickets are part of the repo.
The difference is that the Jira ticket is for everyone involved in a project (business analyst, UI designer, QA, support, DBA), while commit messages are written with developers being almost exclusive audience. PRJ-123 might explain why an end user might need it, but the commit message explains why the change (diff) is the way that it is. The ticket answers requirements-level questions, the commit message answers code-level questions. Commit messages are useful both during the review and when a future maintainer is reading the code.
> Additionally, if a change requires multiple commits, you don't want to be repeating the justifications for the entire feature in every commit message. It's redundant. But the commits will all be tied together by the ticket reference in the commit message.
Different commits do different things, so require different justifications. Here's a fictional example to demonstrate:
First commit:
Second commit on the same ticket
Side note: the user might not even know that they are looking at Foo and Baz, it might be called something else in the UI they are shown. Whether or not this needs to be included in the commit message depends on the situation.
And later in a commit fixing a bug:
Personal preference I guess, but to me all of those commit messages are way too wordy. I'd probably have:
And then in PRJ-456, I'd also have the comment about bug introduced in commit deadbeef, and link the two JIRAs if it was significant, or just mention it in a comment for a minor fix.
For me personally, nothing else in your commit messages adds value that can't be seen trivially from glancing at the changes.
Git is more robust than Jira. Git log is accessible offline. Jira descriptions exist only as long as people managing the Jira instance are competent and are migrating the necessary data correctly when migrations are needed. Even migrations from one Jira instance to another (e.g. when companies get acquired and two Jira servers get merged) can be extremely brittle.
It's fair that maybe such simple trivial changes don't deserve such a wordy commit message. But these are just fictional examples that I came up with on the spot. Refactorings, new features, and bugfixes can all have various levels of complexity.
A good commit message helps answer the "why?" questions first and foremost. If a diff is fairly large, pointing out the most important change can be useful. Explanations for non-trivial dataflow can sometimes not make sense in separate documentation, but still be relevant in a commit message.
Interesting to see somebody argue out in the wild for what I have been subjected to in the past and have long considered absolute worst practice.
It may be that my perspective is different because my work tends to be in "hard" foundational software (think OS components and programming language tool chains). It's not that customer requirements aren't a thing at all in that kind of work, but they tend to be far removed from the day-to-day and instead, mechanical sympathy rules supreme.
Commit messages need to focus on the software, not on the trappings of the process by which it evolves. Links to tickets can provide helpful context especially for bug fixes, but they belong in the commit message footer.
Your last paragraph is absolutely an anti-pattern at least in this work. If the implementation of a new feature is split over multiple changes, then surely there is something different and important to say about each of those changes. Does your split even make sense otherwise?
The handling of ticket numbers is covered in the FAQ (scroll to the bottom)
[edit] At the bottom of https://scopedcommits.com/ I mean
fixes/feature labels help when generated semver and doing changelogs if you publish them externally or internally.
JIRA tickets can help to, its about giving context to why the commit exists.
I find the 'component' label most helpful in large monorepos.
Exactly. The commit message is supposed to be for the future developer, not to generate changelog.
And the main case when that developer reads the commit message is when he doesn't understand _why_ that commit exists. Not what it changes, but what is the purpose of certain lines. So he runs "blame", sees commits, the original developers are not with the company anymore, the old JIRA may not exist too, and the only hint is the commit message.
https://dev.to/splix/the-why-behind-the-code-2bb1
This, along with the "successful git branching model", are symptoms of the fact that devs overwhelmed with the flexibility of git and look to other people to define standards for them because they that lack the experience to do so for their own requirements.
Actually, this is also similar to classic OOP, where people use a contrived method of structuring their code.
Scope is crucial when working with multiple teams/projects in a monorepo.
Exactly. I think it's funny / telling that my team analyzed Conventional Commits and came to the exact same conclusion the author did.
Scope might not be important to every project, but the feat/bug etc taxonomy might be the least useful focus of them all.
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...
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.
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 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’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”.
You just made me realize why I've always considered 'chore' the most ambiguous type. In addition to being loosely defined ("transparent change with zero functionnal impact"?), this one is indeed a word related to emotion. No wonder it has a more subjective meaning than 'fix' or 'feat'.
This is why I never use it and almost always pick 'feat' to please the linter. Because I can't help considering that any change worth committing is improving the quality of the code in one way or the other, and thus a feature.
I found an alternative word: "upkeep"
Same idea without the pejorative aspect.
I wouldn't spend any sort of effort on this fight but that does seem quite a lot better
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.
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.
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.
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.
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
Ok... but why does it need to be in the title?
It's probably kinda helpful in git blame.
if IDE supports converting them into clickable links, then scrolling through a log in its Git integration (kinda like `git log --oneline`) will be a convenient list of links to issues. If the commit messages are good, you just skip over the Jira issue/ticket key/ID. If what you want is to see the requirements of a feature or steps to reproduce of a bug or some other context for the ticket, then a clickable link is very convenient. Of course, sometimes it does make sense to include some of that information in the commit message as well.
When working in big teams, it can be very hard to increase the usefulness of commit messages. On the other hand, enforcing inclusion of a Jira issue key in commit messages is easy to implement. Relying on issue tracker descriptions can be a difficult proposition as well. Quality of individual ticket descriptions can be low; depending on how responsibility for maintenance is handled, the bug tracker migrations can sometimes be handled improperly and information can be more easily lost than in a Git log.
If the IDE supports that it can easily extract the issue number/link from the commit body too.
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.
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.
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.
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.
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.
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.
I think you’re the first person in this comment section to mention this. Git has a structure for machine-readable structured data. Put it there, not in free text fields for humans.
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.
It's only a convention around commits suggesting to prefix them with certain short words, there's nothing stopping anyone from including issue numbers.
All ours at work do: "feat[component]: DEV-1234: description"
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 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 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 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.
The article explains why this does not work properly.
Yeah the article is wrong
Can you elaborate?
Why does that need to go in the title though? Just put some magic in the commit bodies, if you want to do versioning in that weird way. Then you aren't restricted to a single word either.
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.
https://knowyourmeme.com/memes/stop-doing-math
There is a meme that inspires some of this genre of title, fwiw
I came to say something similar.
I don't like conventional commits much neither, but let the people use whatever they want!
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.
Because you don't get attention if you don't write deliberately inflammatory content.
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.
Edit: Looks like they changed the title to be less provocative. Good for them
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.
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.
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.
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 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.
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.
+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.
Inverting the order actually addresses my primary annoyance: what is a feature?!
> refactor(core): Update webmcp support to use document.modelContext
As the author points out, the line between a fix, an improvement, and general clean-up is blurry and dividing each semantic change into its own commit (and possibly squashed later anyway) is just creating work for no one's benefit.
I think Conventional Commits are just an artifact of trying to automate SemVer rather than solving any of the other problems directly. I don't think changelogs should be automated anyway - I can `git log` that if I want a list. A changelog is an opportunity to communicate to a wider audience what is actually going on under the hood.
“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
He confuses changelog with release notes. Doesnt know how to name commits and probably doesnt know how to name symbols either. Skill issue and he’s sad, now in public. Move on…
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.
Exactly. People latch onto these perfunctory standards because it’s easier than understanding and clearly communicating the work they’ve done.
Or they could be used as a stepping stone in teaching people the value of being able to summarize what they've done?
How does typing “fix:” or “feat:” get you a step closer to being thoughtful?
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.
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.
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.
You never need to write "fix", or "prevent" if you write a good message. Nobody says "fixed the car by changing the flat tire" or "Go prevent engine wear by getting an oil change today. You say "Change the flat tire", or "Change the oil".
You can do the same when you write commit messages. "Wrap user and account update in a transaction" - "Delete temp files after use".
I disagree. I think the commit description should be "stop the engine wear", not "change the oil". I much prefer commit messages describing why you did the changes, because the explanation of what you did is already there - the code diff itself.
Whatever describes the change better. Sometimes the issue is easier to describe "fix: car steers in slalom". Where the solution would have been subtle interaction between 3 different components that only occurs in 3rd gear.
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).
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.
All the items being discussed are useful things to think about and cover in the commit message. Certainly if after reading a commit message I do not know what was intended (eg. “is this a refactor that is not intended to change behaviour or not?”) then the commit message is missing something. What I object to is overloading all of this into the first line. The subject should be reserved for the most relevant information and is limited in length. Forcing committers to collapse a bunch of metadata into it makes it less useful for that purpose.
Keep a Changelog[0] maintainer here, weirdly seeing this while deep into work on way overdue 2.0 "release"[1], which should be out very soon.
I've had to contend with Conventional Commits both in the OSS world and at work as it proliferated from what seemed to me like robotic adoption by folks who were even loosely associated with the Angular ecosystem (remember that?).
I've always had a stance with KAC that folks trying to automate changelog creation (prior to LLM rise, mind you) were focusing on the wrong thing. I still think there's a fundamental difference in focus between what you write in a git commit and what you present in a changelog.
I know there are fundamental philosophical differences for folks who were used to HISTORY vs. NEWS vs. CHANGELOG but with the growing adoption of KAC-like CHANGELOG.md files and Release Notes (often not synonymous) I think we're thankfully past the weird era were maintainers dumped raw git log ranges between two tags and called that a changelog. I'm sure some still do it. But that's what Conventional Commits tries to replicate.
What's really odd to me is that this assumes (broadly) that every single commit in a repository is relevant to the eventual version release changelog (or release notes). Even if you assume some CC types get filtered and deprioritized from generated changelogs by some tools, it's still a huge miss on what communicating about a release typically means: these change likely matter to you as a package dependent or direct user, while others were omitted for good reason.
I'm trying to articulate that much more clearly in KAC 2.0 because there's a fundamental paradigm shift when a robot can now analyze recent work (yours or theirs) and craft changelog entries that appropriately shift the audience perspective from "git message for me/us in the future to understand this change" to "changelog entry for you/them to know what this group of changes means".
[0]: https://keepachangelog.com
[1]: https://github.com/olivierlacan/keep-a-changelog/pull/600 if anyone's curious and wants to get involved
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.
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.
I totally agree with the sentiment behind this, so much so that I also made my own standard a while ago, https://commits-with-character.org/ an incredibly light addition to the Git Book guidelines, and also gives more priority to scope. It’s been working really well for me in my small projects.
Wait. i am already struggling with 50 columns for the title, now i have add this `<type>[scope]:` bloat to it? How are these people doing both "Conventional Commits" and 50-72 at the same time?
Broken promise 1 (Automatically generating CHANGELOGs) is spot on, especially in a monorepo with multiple released artifacts. A single commit could be a breaking change in one package and refactor in another. But the changelog tools see one commit and include it in both changelogs.
Another issue is that once the commit lands on trunk, you can’t revise the entry without editing history. You have to remember to fix it after the changelog is generated.
Changesets (https://github.com/changesets/changesets) is a much better approach. We adopted it in Endo (https://github.com/endojs/endo/tree/master/.changeset) and it’s been a clear improvement.
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.
The issue with all of these schemes is less about the format and more about the semantics itself. What are all the actions that can be done to a codebase and what is a controlled vocabulary that encapsulates those? Then it doesn’t matter what system you use.
I spent some time recently coming to the conclusion that I did not prefer CC, but wanting some reliable structure. In the end, I found I was coming up with convoluted schemes that were getting in the way of actually solving my real problems and just settled on the tried and true:
I don’t consider this to be a complete taxonomy, but it does let me get on with my day and covers most things, especially when combined with thoughtful commit messages.
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.
Making an opinionated absolute statement about something that's widely used and argued about isn't even logical. If nobody got any benefit, it wouldn't be a thing.
The CC standard may not be for everyone, but having some convention is often helpful. git log --pretty=oneline of structured format gives you broad filtering that's useful. Just writing like a human doesn't give you that ability and you're forced to read every line.
There’s a much less awkward way to keep a change log:
Keep a change log.
I 100% agree. I found https://keepachangelog.com/en/1.1.0/ as I was writing the article which advocates for exactly this!
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 stick with Conventional Commits as a standardised way for communicating changes. Most contributions in the form of open PRs are squashed before merging into base branches. A team member can commit as personally wished in the feature branch. I still use CC for my own sanity and I’m very glad I do comparatively to what usually find in others feature branch commit histories.
Without standards most developers I’ve seen are very careless.
I generally work with changesets to curate changes at the time of contribution in accordance to semantic versioning.
What’s great about CC is the simplicity.
Conventional Commit messages have big https://goomics.net/361 energy. Or at least the mechanisms that repositories use to programmatically enforce their use.
(I can't believe nobody has pointed this out yet.)
This entire essay is just about how it should be "<scope> <optional type>" instead of "<type> <optional scope>"?
The essay gives a bunch of reasons to drop the "type" altogether and just use "<optional scope>" as prefix. The type either doesn't really mean anything or is redundant when writing commit headlines as English sentences. In a message like "Prevent thing from happening" the verb "prevent" is already basically a synonym for "fix". Similarly "Add" or "Support" likely implies "feat"/"feature".
To some extent the "type" is simply about trying to limit/standardize the number of possible "verbs" to start a commit headline with, in which case Conventional Commits made the mistake of mixing verbs and nouns (fix and refactor are verbs but feature and chore are nouns) and adding distracting punctuation where English prefers none between the Verb and its direct object in a "Verb the thing" sentence. "Verb: the thing" only ever really looks awkward.
But also do we really want to limit the possible number of verbs that a headline sentence can start with when making commits? "Fix" and "Prevent" may often act like synonyms but there are connotative differences. In some cases "Prevent" may be a shorter way to explain why something needed to be fixed in a headline because "prevent" also says "stop a thing from happening that wasn't supposed to happen" whereas "fix" alone may not yield that extra context. The top line of a commit should be a short and sweet headline and sometimes the cleanest way to do that is to use the full gamut of English verbs at your disposal to tell the right story as quickly as possible.
> fix and refactor
Both fix and refactor are both verbs and nouns
In my experience both are more often in noun form with an article ("a fix" and "a refactor") because they are both sort of awkward alone. But sure I can appreciate that's probably how we got the set of words that we did that they were all picked as nouns and only in juxtaposition does it become more obvious to me that I think it might have been better to have picked just verbs. I can see the sorts of thoughts that led to "noun: verb the object" as a "good" headline format, especially when the "noun:" is considered the important part of the headline. But only before realizing it is generally redundant between "noun" and "verb" and "noun:" might not really be all that important (as the article points out flaws in).
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 is the kind of thing where the extent to which people get worked up over it far exceeds the benefit of actually doing so.
Is it theoretically possible that people can write good commit messages without a framework? Yes. Does that work out in practice across entire teams? No. Any kind of a convention for commit messages is an improvement.
Beyond that, type > scope vs scope > type or whatever is splitting hairs. The juice of that debate is not worth the squeeze.
As a reviewer, I love type first because it sets expectations for what I'm going to look at. Similar if I'm bisecting or doing other history operations.
I don't do automated changelogs or versioning but it also makes it faster for me to do so.
I really dislike focusing on issue ids. I only want to jump to another tool if I need more information, so put it in the footer for after I've read what is there, like a front page news article giving you the option to go to the back to read more. Worst case that I've seen is people that think the Issue ID is all you need.
I feel +/- line counts alone give a good sense of whether something is a fix, a refactor, new feature/component.
After that it’s great to know where is primarily intended to be impacted.
Then look for what the change is and does.
There are some good ideas in this proposal but the author is creating a false dichotomy by saying the current standard should be scrapped. Two things can coexist and both be good. I hope the author reconsiders their approach in their future promotion of their idea.
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.)
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 personally like it for one of my work projects. Its the only one we use it on. Its a repo with the android and iOS app. I like the conventional commits because when doing releases, I can look between two tags and pick out what I need to put in the "What's new in this release" section. I try to not just do the normal, "bug fixes and various improvements," in that section, but what we actually did. Also helping make clear what went into a release branch/what needs to be cherry picked into a release branch. I also don't automate the generation of the "Whats new" section. I just take a look at all the commits between tags.
We also tend to do something like
bug-ios: <case name>
feat-android: <case name>
So we don't have generic stuff like
bug-ios: fix memory issue
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 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.
I like using conventional commits but I’ve often wondered if some sort of tagging/labeling using git-notes wouldn’t be better: https://git-scm.com/docs/git-notes
I’m just unsure that the short title is the ideal place to put this kind of tagging info: the kind of fix, and optionally, the relevant component(s). I find sometimes that can take up the majority of the title.
A forge could consume the git-notes and decorate a commit/pr accordingly. Heck, GitHub PRs already have a labeling system in place, just have to add some glue.
I agree with the sentiments -- knowing the scope of a change is more essential, in most cases, than knowing whether the change was a "fix" or a "feature" -- but much of the scope in a project can be gleaned from the files which were touched. So the use case of, "i need to quickly at a glance determine what commits touched what parts of the project" can be answered with some variation on
I used and use Conventional Commits in private and professional projects and I think they have a place.
That being said, when I finally committed to using them something in me broke. Most of my career work was double faced. One face to the customer where you need to keep Tatemae under all circumstances (UI, Tickets, etc.). The other was the code and commit messages where you still kept your professionalism but you could be open and speak the language of your peers.
This time is over, maybe for good, but a tiny part of me misses it.
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.
From my own experience in big tech and various OSS things, the crux of this piece rests on this whole scope not being focal point misses that in general the other practice is making sure PRs have limited scope in general so it's marginalized, i.e. reducing blast radius or too big of a change at once by design is implied.
I've been a developer for 40 years. Used VC since rcs. If only people had such pedantry for the actual code, the world would be a better place. I look at the author way more than I read a commit message, next the date and then the code. Never much else.
Conventional commits is one of the weirder cargo-culty things we do in this industry. I do take issue with this, though:
> Automatically determining a semantic version bump (based on the types of commits landed): This sounds nice, but the realities of software engineering often interfere significantly with the viability of accurately accomplishing this... imagine a situation where the breaking change you introduced was actually so breaking that you have to revert it... maybe the breakage is subtle and you don’t realise a change is a breaking change when you make the change. Only in retrospect realise that it’s breaking. You will incorrectly increment a minor/patch version when a major version bump is necessary...say you later add a commit which, in composition with a previously breaking commit, results in a diff which is not breaking. Similar to the revert situation, tooling would incorrectly identify a breaking change.
This is a problem with Semver, not conventional commits. You're liable to do this regardless of how your commits are formatted, which is one of several reasons why conventional commits are silly. But in this case, Semver itself drew semantic lines that aren't clear, and are easily broken.
the article mentions three types of stakeholders: contributors, debuggers and incident responders. it entirely fails to mentions consumers, who mostly care about backwards compatibility of changes, and thus about the type of a change. once the type is established, e.g. a change is breakimg, the consumer next cares about the scope to make downstream adjustments.
the part about broken promises regarding breaking changes is _kind of_ fair, but only assuming tooling isn't able to track reverts. accidental breakages occure with every approach and better to have an approximation than no information at all.
Related. Others?
ReleaseJet – Release notes from issue labels, no Conventional Commits - https://news.ycombinator.com/item?id=47847605 - April 2026 (1 comment)
Why Use Conventional Commits? - https://news.ycombinator.com/item?id=46940152 - Feb 2026 (1 comment)
Conventional Commits Considered Harmful - https://news.ycombinator.com/item?id=46019218 - Nov 2025 (1 comment)
Conventional Commits Considered Harmful - https://news.ycombinator.com/item?id=45420887 - Sept 2025 (1 comment)
Conventional Commits makes me sad - https://news.ycombinator.com/item?id=44482546 - July 2025 (2 comments)
A specification for adding human/machine readable meaning to commit messages - https://news.ycombinator.com/item?id=40740669 - June 2024 (2 comments)
A specification for adding human and machine readable meaning to commit messages - https://news.ycombinator.com/item?id=34660646 - Feb 2023 (48 comments)
Ask HN: Are you still using conventional commits? If not why not? - https://news.ycombinator.com/item?id=33525754 - Nov 2022 (4 comments)
Conventional Commits - https://news.ycombinator.com/item?id=30950377 - April 2022 (1 comment)
I Hate Conventional Commits - https://news.ycombinator.com/item?id=29924976 - Jan 2022 (1 comment)
Conventional Commits - https://news.ycombinator.com/item?id=24208815 - Aug 2020 (23 comments)
Conventional Commits: A specification for structured commit messages - https://news.ycombinator.com/item?id=21125669 - Oct 2019 (95 comments)
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.
Thank you for the thorough write up! I just thought about this today and needed the set of arguments and examples you brought forward. Especially the pointers to NixOS et.al. were informative. Thanks!
I have never once considered conventional commits to be about human understanding, but more about automation (release notes, changelogs, and workflows).
The commit description and the pull request are for humans.
The best commit message: is what is meaningful to a future you 1 week from now, no further otherwise takes up the least time to think about right now
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.
So much commit hygiene and fuss appears git induced. Use something other than git and the problems disappear.
I prefer how golang/go commits are organized. Simple but working setup.
And then you have me, using gitmoji
Why not both? Scope is definitely important. But type is also important: - prioritization: bugfix > docs - visibility: are we spending more time on bug fixes or features?
Also, we let AI write the code, are we STILL writing commit messages by hand??
Yes. It’s just more bike shedding. Write helpful comments if you care about such things. Example: https://www.sqlite.org/src/timeline
The proposal, https://scopedcommits.com/, is not that different.
My gripe about conventional commits is the redundancy: fix(ci): fix the foobar
Commits should have no information in them. Teams should be aligned on the design of their software, and all the information about that software should be apparent from its source code.
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.
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 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.
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
- nixpkgs
In practice, when conventional commits are used with git emojis, they look like “scope: what is done” already (“<emoji> <issue-id> scope: …”)
No. If you use ‘star’ for ‘feature’ that does not convey the extent of the change.
You know what lacks focus? This whole article. Oh, and also individual styles of commit messages. You know what’s a waste of everyone’s time when you’re building technology in 2026? How to write and summarize what you’re work is doing.
Conventional commits doesn’t make a promise, it’s a specification. Words have power and meaning, this viewpoint is about more than a spec, it’s about the popularity and relevance that they clearly despise.
Conventional commits are like BEM syntax for CSS, it works if you pay attention. It’s structure around what developers do, which thoughtful limits. What is the problem with that? Is it the only way? No. But to say it’s encouraging the “wrong things” pshhhh
This author’s take is dog water for coders who yearn to be controversial and (clearly) focus on the wrong things.
Old man yells at clouds
This seems very nitpicky
In other words a perfect topic for HN
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.
I'm not getting why "scope" gets any priority at all. Are filenames not attached to a commit for those exceedingly rare cases where you're looking for which files are thrashing?
Also not getting the downvotes. It's not a rhetorical question; it's a question looking for an answer. If somebody could explain why "Scope" gets should get precious space in the title of a commit, I'd be grateful. It seems inconsistent with the reasoning used to remove other pieces of information. If "feature request" or "bug fix" doesn't make it into the commit title because it's usually apparent from the description, then surely the same is true for "scope".