6 ms·

Commit Messages Don’t Matter

24 points by rckrd 4y ago

Juliate 4y ago
On a more broader scope than software source code, historians may disagree. Commit messages are like timed notes, or artifacts opportunities to explain the path of evolution of a code base, while explicitly pointing at it.
forgotmypw17 4y ago
Commit messages are so that I can figure out why I added that particular line of code a year later.
trowawaylol 4y ago
wrong
- dallasgutauckis 4y ago
  yeet
emrah 4y ago
It seems like the author is not aware of IDE annotation feature that allows one to inspect the latest commit that modified any line of code. Better commit message helps there for sure. I use this all the time, saves time not having to lookup the PR and piece together why something changed by manual inspection. Better commit messages would be more helpful with PR review process if it was easier to review commit by commit which is possible but rather cumbersome.
eof 4y ago
As someone who has both cursed and blessed the names popping up in git blame as I’m trying to understand why something is the way it is; I cannot even begin to sympathize with this. The author has a seemingly naive notion of the lifecycle code; commit messages matter a lot less if you have deep thorough documentation in the general case. But obviously not all code is being written in those types of environments. In fact I’d venture the vast majority of commits have no associated code review thread. Sometimes my little project I’m working on myself , which has no code reviews, eventually gets grows and has others involved; but the early history remains.
- rjbwork 4y ago
  Indeed. Author seems like someone who has never used git blame or something. Also, given that I originally used mercurial for the first few companies I worked at in my career, this idea of just blowing away history with squashes and rebases etc is anathema to me.
tomstuart 4y ago
I have neither the motivation nor the energy to start an internet argument about it, but I’d like to reassure the casual reader that this post is promoting a minority viewpoint.
- einpoklum 4y ago
  Minority viewpoint, but majority practice :-(
- staticassertion 4y ago
  Not sure there's evidence there. I bet if you look over the vast majority of commit messages you will find that they're "lol fuck" or "whoops". The reality is that developers convey intent through pull requests and rarely go through a commit log. Most people use commits as "ctrl s", which means commit messages are just some dumb shit in the way of me backing up my files.
  - michaelmior 4y ago
    I disagree that the vast majority of commit messages are you describe. But even if that were the case, I don't think the majority of commit messages being bad would mean they don't matter.
    - falcolas 4y ago
      Thought exercise: If comments are often considered harmful because of their lacking quality, why would commit messages be considered helpful when they suffer from similar issues?
      - marcosdumay 4y ago
        One reason is that commit messages do not become stale. Anyway, software development as a whole decided on a pretty stable set of comments that are considered helpful. Commit messages are clearly in there, as well as API elements description.
NegativeLatency 4y ago
The author ignores the possibility of writing a terse but just descriptive enough message that gives an idea of what the changes were, which I would call a "good" commit message.
- softfalcon 4y ago
  Yes, this is what I do. It has saved my ass more times than I can remember.
softfalcon 4y ago
My team writes good commit messages… I had to revert a giant feature due to unforeseen consequences. Because of this I didn’t have to diff anything, I selected the target commits, made a revert commit, and was done. Saved me hours of time and headaches. This is my anecdotal example from the last month for why this article is wrong. Write good commit messages, people can and do read them. When it matters, it matters a lot.
phabricator 4y ago
git reflog would be very difficult to use without them, wouldn't it?
ricardobeat 4y ago
> Proper style? Formatting. Imperative voice. Capitalization. Hard wraps. Correct, those don't matter much. On the other hand, describing what the change is about matters a lot. It is 10x easier to review a merge request when you can see discrete steps that make sense (ex: update method X, update route Y that calls X, update all code paths that use route Y, update client to handle new data) vs one big jumble of "stuff", "fix it", "update getCustomers" that touches 27 places at once.
- TheSoftwareGuy 4y ago
  To counter, any merge request with more than 2-3 commits is probably too big anyway
  - ricardobeat 4y ago
    Not a fan of those arbitrary limits. It's all about being able to quickly understand the changes and their reason to be. If splitting the updates in smaller increments help, then so be it, and I'll take ten tidy small commits over two large ones any day.
    - morelisp 4y ago
      PR guidelines - Git best practices generally - are one of those situations where you must provide concrete guidelines but also never, ever make them a hard rule. If you don't have any you'll get endless "fix" "oops" +9876/-1234 changes, and if you make them a hard rule you'll never get anything useful done as people spend all day trying to please the aesthetic preference of a team lead who probably hasn't written a more than a single two line commit in years.
  - wizofaus 4y ago
    Huh? The number of commits is irrelevant - the number of changed lines/ files is what matters. 20 commits can result in a couple of lines in one file changing (I've seen it happen) and 1 commit can have 100s of files changed (usually when some commonly used symbol has been renamed).
- 4y ago
james-skemp 4y ago
Based upon username will assume author shared it here: You've neglected to state what commit messages do matter, unless you think none do. In my experience, commit messages only don't matter if the code is never used beyond the first creation. Once you have to maintain the code, commit messages absolutely matter. Does it need to include the granular details mentioned in the article? No. But commit messages help determine what commits should be reviewed during maintenance (including adding new functionality). (I also experienced a touch of cosmic fear while reading the article, thinking about someone who might rebase or squash every commit, leaving only one commit for an entire repo.)
gspencley 4y ago
It wholely depends on what you are hoping to get out of the commit messages. I don't want to see the local commit history of individual developers in the commit history of any shared branches (be it mainline branches or shared development branches). What I do want to see is a history of pull request merges. I don't care how they are formatted (and this is often done automatically) but it matters that if I want to check out a historical changeset that I can. This is particularly useful when there are regression bugs that managed to slip through the QA and automated testing processes and it is unclear what caused them and when. It is nice to be able to go through the commit log and identify suspect work items, check out the commits during that time and see what they changed. How you format the commit messages isn't that import as long as your pull-requests are squashed-merged (to suppress local dev workflow commits that aren't relevant to the team) and the commit messages facilitate doing that with something that links back to a work item.
- afterburner5 4y ago
  Louder, for the purists at the back!
einpoklum 4y ago
> Commit messages are probably one of the worst places for documentation They're a bad place for documenting the repository for users. They're about the sole place to document what's in the _commit_... > and a common source of bikeshedding. You can bikeshed anything if you like. But I'll grant the author's claim that bikeshedding the exact format convention of commit messages is excessive. If someone wrote "Added feature X" as opposed to "Add feature X" - yeah, that doesn't really matter. On the other hand, if the first line of a commit message is extremely broad and vague, this makes it difficult for the developer browsing the commit history in a one-line-per-commit view. > Adding in information about what files have changed doesn't make sense It can makes sense if it's essential to the commit, e.g. "Moved `foo` from `file1.h` to `file2.h`". But TBH - this is bikeshedding. > this information is more easily stored by looking at the diff Ah, but the whole point is that you want to _avoid_ looking at the diffs of many commits. > Information about why and how often have better homes. Nope. > There's the code review history, the bug tracker These are not part of the VCS commit history, and may not even exist at all. > the code comments So, we want to put commit comments as actual comments now? No. > and the actual documentation. No. The actual documentation is: 1. Intended for users of the repository rather than developers/maintainers of the repository. 2. Documents all commits up some release (or up to some commit). > Your commit message essays will probably be lost or munged anyway – squashed, merge committed, or rebased. So will our code... but the point is that, after such squashes etc., there is still a commit history for which it is important and useful to have commit messages.
steveBK123 4y ago
The worst commit message bureaucracy is the requirement to link to a story / feat|bug|etc classification and perfect message formatting or it gets rejected. My firm went through 3 different ticket systems in 5 years, including a round trip to Jira. Teams/apps migrated to different Jira projects, repos got split apart/merged, tickets were archived, etc. So the commit blocking requirement of having a link to the story ends up pointing to dead ends or stuff you may not have access to quite often. This is the kind of stuff that causes senior devs to commit less often, or to have an always-open "misc" ticket to book everything to, with a copy-paste ready commit message in the proper format to pass checks.
- rvdginste 4y ago
  As a team lead I insist on a link to a ticket for stuff that is related to a ticket. When moving to another ticket system, I insist either on keeping older projects on the old system, or alternatively on migrating old tickets to the new system and keeping the original references; the same way I insist on keeping history when moving from one source control system to another one. Also... why would a company go through 3 different ticket systems in 5 years? That must cost a lot and definitely is not gonna help convincing people to use it...
  - steveBK123 4y ago
    hard to imagine, but many IT orgs are poorly run!
ptx 4y ago
> Your commit message essays will probably be lost or munged anyway – squashed, merge committed, or rebased. Yes, because commit messages do matter and rebasing/squashing is how you clean up your initial draft commits. (Merging doesn't lose or munge the commits.)
afterburner5 4y ago
I can see where the author's coming from. However, my approach for a PR might be a bit of a mix. Normally, I aim to make a PR be reviewable, commit by commit. However, in some cases, due to a semicolon missing (you get the point), or some instance where I'm being daft, or me bumbling in the dark trying to fix a piece of ancient, undocumented code, the history might end up being less than clean. The messages will always describe my train of thought in those scenarios, but the overall history wouldn't be cut and dry. I tend not to worry about that and generally just squash the commits when I merge, so that, on main, there's a single commit for a particular feature. That's an overall piece of work I did. If someone wants to dig into a feature commit by commit, they can typically check the PR out and do it that way, but in practice, I've rarely seen that happen, and if it did, it was more for the overall feature rather than any one commit. So, overall, it's not that commit messages don't matter, but rather that, while a pristine history is always nice to see, it's not always possible without unnecessary head scratching that generally just costs more dev time for very little benefit.
- staticassertion 4y ago
  Does anyone actually review PRs commit by commit?
  - masklinn 4y ago
    When the history is designed for that, sure. Although having the review tool also designed for it makes this much more convenient and comfortable. Github, sadly, very much is not designed for that.
- masklinn 4y ago
  You know that you can edit the history in order to fold the small fixes and mistakes back into the commit they belong to right? It’s not an all or nothing situation. > If someone wants to dig into a feature commit by commit, they can typically check the PR out and do it that way, but in practice, I've rarely seen that happen Of course not, it’s a pain in the ass having to go back to the PR and trawl through a commits sequence you describe as essentially broken.
morelisp 4y ago
Rickard is just on a roll of absolute garbage lately. Why does this get posted?
LennyWhiteJr 4y ago
Commit messages don’t matter. In fact they matter so little that I'm going to write a blog post about how much they don't matter. Commit messages are probably one of the worst places for documentation and a common source of bikeshedding. So let me kickstart some more bikeshedding since there's not enough already.
eminence32 4y ago
I work at a large software company that has, for decades, operated without any commit messages whatsoever. When you get the days latest code in your workspace, you know what files are changed, but not why (and often not who). Has our company imploded? No. But you absolutely feel this lack of information whenever you wonder "hmm, why is this line of code the way it is". As we've transitioned to git, we don't have a universal culture of writing commit messages, and I wish we did.
epolanski 4y ago
Amen. My company has a fixation with it and yet no use. Zero. The only instance where it paid off was to include the jira task code in the second line of the commit, but this also has been short sighted and rarely useful because most discussion about PRs happens on slack and teams, not on Jira.
knodi 4y ago
why not just go back to svn...
einherjae 4y ago
Bait, please ignore.
davedunkin 4y ago
This sounds like the advice of someone who hasn’t worked in codebases mature enough to go through multiple source control system and issue tracking system changes. The commit message is the one piece of documentation most likely to survive. A commit message that explains why the change was made can be very valuable when the code review comments and bug report are no longer available.
subw00f 4y ago
Just write why something changed, not what, nobody will read the log like a book, they will just use blame. The rest is bs.
DSMan195276 4y ago
> There's the code review history, the bug tracker, the code comments, and the actual documentation. All of which are probably better places for real knowledge to be stored. The funny thing is that I've been through many of these systems in the past years, and each time we mostly lost all the previous PRs and comments, but all my commit messages are still there preserved in the history. These ideas are all a "better place" until it's suddenly all gone because it's not actually a part of your code history and can't easily be moved.
tuetuopay 4y ago
I wholeheartedly disagree. Bug tracker? It can change. Reviews discussion? The tool can change. You get the point. As an added pain point, I don't want to juggle different tools to get the whole picture about changes. I don't want to copy/paste a Jira ticket reference in my browser from my terminal to get the reasoning about the change. I don't want to copy/paste a bugtracker ID to get the reasoning about the change. Commit messages are here for a reason, and it is to document the change. I find them invaluable when digging through a codebase with plain git tools, tig, or the git integration of an IDE. Conversely, this is why I hate squashes of PRs of more than X commits. Just no.
- groestl 4y ago
  > this is why I hate squashes of PRs I like them because of the linear history, but the commit message should keep the explanation for _all_ the changes.
  - tuetuopay 4y ago
    For this, I often configure repos to only accept "fast-forward merges", as to keep a linear history. The added benefit is increased by good splitting of commits as conflicts will be resolved commit by commit rather than the whole PR with a possibly huge conflict to solve.
- usrusr 4y ago
  But commit messages can also be too fine-grained, at least if you are not into the squashing game. And a level of conciseness that is valuable in commits might be a little too short for truly meaningful context years later. My preferred pattern is some "why" in the message, as a soft "should", and a external reference to some potentially longer and perhaps not so fine-grained ticket/story/bugtracker-id as a much stronger "should". That's where longer form prose has its place, or some media, and most importantly after the fact amendments without the hassle of history rewriting. And once that pattern is 80% established, even the emotional outlet of an occasional "whoopsie" message can be totally worth the cost, if it's actually "whoopsie (WHYJIRA-12345)" Anything occasionally gets lost. (some languages have surprisingly useful decompiles..) It's probably best if all approaches are taken in parallel. And taken reasonably well (as opposed to gold plating), enough to be workable alone in a pinch but decidedly not fully redundant. Comments, commits and out-of-band tickets all have their place and neither is a good substitute for the others. Allow them to complement each other, and strive for just enough overlap to make losses somewhat tolerable.
nix0n 4y ago
Is there some trick I don't know about, to quickly go from a source line, to the PR discussion? If there is, the PR discussion might be the right place for explanation, but if not, the commit message is still valuable.
- masklinn 4y ago
  > Is there some trick I don't know about, to quickly go from a source line, to the PR discussion? Assuming people are religious about putting the PR ID in the commit message, you might be able to relatively easily jump from the commit you found normally (e.g. blame-diving or via the log) to the PR. Whatever your tool might even be able to do the jump in one shot, though I think it jetbrains stuff it usually takes two (“open in > Github” from the commit, and from there click the reference to the PR). But obviously that means you did go through the commit message, and having had a good summary in the commit message would likely have saved you the trouble.
abrax3141 4y ago
I use selections from random poems as my commit messages in order to confuse the AIs of the future that intend to learn from them.
francisofascii 4y ago
This sounds penny wise, pound foolish. If I spend half a day tracking down a two or three line bug fix in a large codebase, you bet I will spend the extra minute it takes to make a decent commit message.
austinl 4y ago
I think titles of PRs matter, and at least for me, they're often identical to the commit message (either a one commit PR, or multiple commits git-squashed for one PR). I suppose it depends on your use case, one example is that I use these titles written by myself and co-workers to write beta release notes each week, which folks seem to really appreciate.
pjs_ 4y ago
Looking fwd to going viral multiple times on Hacker News over the course of the next few months with such irresistible blog posts as: - Don't be afraid to roll your own crypto - Why using string types for numeric data is actually a great idea - Let's put all the code in one really big function
becquerel 4y ago
The author's complaints could equally be applied to naming branches, but I suspect he would find it difficult to work if all of our branches were named 'a', 'bbbbb' 'seroiuwegonw' and the like. Without messages, commits are only identifiable by arbitrary and meaningless strings of letters and digits. This would make git bisect needlessly more difficult, if nothing else.
fdr 4y ago
I disagree with the author. Text explaining a "why" are often contemporaneous. To put it all in the source text would be too bloated and too prone to bitrotting into misinformation to be useful. To increase concision to the point where bitrot is unlikely loses useful contemporaneous detail. So, I prefer concise comments that are highly salient and unlikely to turn into misinformation, usually about key details on a mechanism where subtle mistake is more likely than the norm, and detailed commit messages on contemporary justification. Also, the author mentions the commit messages being "probably lost." I'm not sure what the author is doing to get themselves into that situation. I work on code bases with good commit messages. I use emacs's vc-annotate with regularity.
Tehnix 4y ago
This will largely depend on your workflow, but in a PR-based workflow, I've for a while now held the opinion that individual commit messages are useless to me in the history of the code, and that a squash with a final description + summary is the best way to go. There'll be cases where the following don't match, so let me explain what this is based on: - In our flow, a PR is small and is the unit of work that is guaranteed to compile/work (tested against master before merge) - Each individual commit inside the PR can be helpful for a reviewer, but the code should stand on its own and your commits (inside the PR) should not be a source of documentation - I have never been able to pick out a commit at random from non-squashed PRs, and be sure it will compile. Unless you're running CI locally before committing, you simply do not know - Spending a ton of time to create a nice history inside a PR is a waste of time, since throughout review or experimentation you will need to adjust work that you previously committed as if you had everything thought out - the alternative is aggressive history rewriting and force pushing which is very quickly a huge mess - Finally, it tremendously lowers the bar of what's required from each developer, which scales much better, when all you have to do is take extra care in the final title and description Now, most importantly, squashing PRs is tremendously helpful when digging around the code and having something like Gitlens explaining the changes: - Commits from a merge commit are on average a lie of the final reason, and very often something like adjusting formatting, fixing linting, which makes the original reason disappear as this was the latest change - Viewing the squashed PR title and description gives me so much more information and if I want to dive into the specifics, the PR itself is worth so much more than any individual commit message will be Again, this is something that fits with a specific workflow. If you're developing directly against master or similar styles, then obviously this won't suit you. --- The review and history part is actually something that is interesting to dive into for the importance of commit messages and what you and your teams expectations are. I'd recommend explicitly talking about this with your team :)
TrianguloY 4y ago
* more changes < feature/PD456 * more changes * more changes * changes < origin/feature/PD456 A week later: "what did I do here? Let me check the source code" (10 minutes of checking changes trying to understand what it does) No thanks, I prefer to at least write some minimal indications like * cleanup and tweaks < feature/PD456 * implemented feature, new test pass * added new test (now fails) * updated version to 1.2.3 < origin/feature/PD456
jscholes 4y ago
Do you know what doesn't matter? Articles about whether commit messages do or don't. What matters is the art of documenting things, somewhere, and that place should be the one that works for your team. If it's commit messages today, great. If that changes in the future, great. If it's somewhere else entirely already, also fine.
andosteinmetz 4y ago
Having worked with people whose commit messages are along the lines of "update function", my experience has been that when you're trying to find where a bug was introduced, it's quite helpful to review (good) commit messages to quickly get a sense of what concerns a commit was addressing, and what code it's likely to have touched. Speaking for myself, I also find that writing a good commit message is useful in helping me think about what work I've just completed and whether the changes I'm committing form a logical group. Granted, there are all kinds of workflows and I can vaguely imagine some in which commit messages are redundant, but still, I don't think it makes sense to generalize the statement.
tildef 4y ago
I write descriptive commit messages because the code I check in is likely to contain a bug. This bug tends to be discovered a couple of years after I worked on the code. By linking my commit message to an issue and having a good explanation for why I've done what I've done, I can easier get into the mindset I had when I committed the buggy code. I find my life gets less stressful this way. I do agree that just regurgitating the files/classes/methods a commit touches isn't very useful. I'll consider ceasing to write "good" commit messages when I'm confident the code I check in doesn't contain any bugs.
- rvdginste 4y ago
  > I'll consider ceasing to write "good" commit messages when I'm confident the code I check in doesn't contain any bugs. Please don't. As much as it is useful to fix buggy code at a later point, it is the same useful to prevent introducing buggy code at a later point! Never saw some code that looked funny at first sight, and that you considered 'fixing', then checked the commit messages and understood why the code was written the way it is? Fixing it, would have meant introducing a bug.
- wizofaus 4y ago
  If every PR you put up is "likely" to contain a bug, you're doing it wrong.
pierrebai 4y ago
I grep commit history from time to time to find when something was done. It is not useless. I also compose the pull request description from concatenation and editing of the multiple commit messages. Good PR description is essential for... good code reviews. So that the reviewer knows where you are coming from. Sure, there is also code comments, but have a good PR message preps you to read the code., And that good intro comes from commit messages.
zzyzxd 4y ago
Out of curiosity, I took a look at the author's commits on github[1] just to see how bad a person's commits can be when they think "Commit Messages Don't Matter" ... Surprisingly, most of his commits were not bad at all. In fact, most of them started with a clean, short, one-sentence imperative summary in present-tense, followed by multi-line detailed explanation when needed with short line length. They are a lot better than the average commit quality I see in many FOSS projects. 1. https://github.com/search?q=author%3Ar2d4 https://github.com/search?q=author%3Ar2d4
- deleted 4y ago
  [deleted]
TheChaplain 4y ago
I follow the Conventional Commits specification; https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ It's actually quite good and if one takes 30s to write a little more descriptive message of what has been done, it'll help the next person.
rvdginste 4y ago
I think people who think that commit messages don't matter, should be forced to maintain a code base written by colleagues of the same opinion for the next 5 years.
sys_64738 4y ago
Commit messages should match the bug ID and synopsis of the bug the commit fixes. Failing that it should be a short description (80 chars or less) detailing the functional change.

24 points by rckrd 4y ago

On a more broader scope than software source code, historians may disagree. Commit messages are like timed notes, or artifacts opportunities to explain the path of evolution of a code base, while explicitly pointing at it.

forgotmypw17 4y ago

Commit messages are so that I can figure out why I added that particular line of code a year later.

trowawaylol 4y ago

wrong

dallasgutauckis 4y ago
yeet

emrah 4y ago

It seems like the author is not aware of IDE annotation feature that allows one to inspect the latest commit that modified any line of code. Better commit message helps there for sure. I use this all the time, saves time not having to lookup the PR and piece together why something changed by manual inspection. Better commit messages would be more helpful with PR review process if it was easier to review commit by commit which is possible but rather cumbersome.

eof 4y ago

As someone who has both cursed and blessed the names popping up in git blame as I’m trying to understand why something is the way it is; I cannot even begin to sympathize with this. The author has a seemingly naive notion of the lifecycle code; commit messages matter a lot less if you have deep thorough documentation in the general case. But obviously not all code is being written in those types of environments. In fact I’d venture the vast majority of commits have no associated code review thread. Sometimes my little project I’m working on myself , which has no code reviews, eventually gets grows and has others involved; but the early history remains.

rjbwork 4y ago
Indeed. Author seems like someone who has never used git blame or something. Also, given that I originally used mercurial for the first few companies I worked at in my career, this idea of just blowing away history with squashes and rebases etc is anathema to me.

tomstuart 4y ago

I have neither the motivation nor the energy to start an internet argument about it, but I’d like to reassure the casual reader that this post is promoting a minority viewpoint.

einpoklum 4y ago
Minority viewpoint, but majority practice :-(
staticassertion 4y ago
Not sure there's evidence there. I bet if you look over the vast majority of commit messages you will find that they're "lol fuck" or "whoops". The reality is that developers convey intent through pull requests and rarely go through a commit log. Most people use commits as "ctrl s", which means commit messages are just some dumb shit in the way of me backing up my files.
- michaelmior 4y ago
  I disagree that the vast majority of commit messages are you describe. But even if that were the case, I don't think the majority of commit messages being bad would mean they don't matter.
  - falcolas 4y ago
    Thought exercise: If comments are often considered harmful because of their lacking quality, why would commit messages be considered helpful when they suffer from similar issues?
    - marcosdumay 4y ago
      One reason is that commit messages do not become stale. Anyway, software development as a whole decided on a pretty stable set of comments that are considered helpful. Commit messages are clearly in there, as well as API elements description.

NegativeLatency 4y ago

The author ignores the possibility of writing a terse but just descriptive enough message that gives an idea of what the changes were, which I would call a "good" commit message.

softfalcon 4y ago
Yes, this is what I do. It has saved my ass more times than I can remember.

softfalcon 4y ago

My team writes good commit messages… I had to revert a giant feature due to unforeseen consequences. Because of this I didn’t have to diff anything, I selected the target commits, made a revert commit, and was done. Saved me hours of time and headaches. This is my anecdotal example from the last month for why this article is wrong. Write good commit messages, people can and do read them. When it matters, it matters a lot.

phabricator 4y ago

git reflog would be very difficult to use without them, wouldn't it?

ricardobeat 4y ago

> Proper style? Formatting. Imperative voice. Capitalization. Hard wraps. Correct, those don't matter much. On the other hand, describing what the change is about matters a lot. It is 10x easier to review a merge request when you can see discrete steps that make sense (ex: update method X, update route Y that calls X, update all code paths that use route Y, update client to handle new data) vs one big jumble of "stuff", "fix it", "update getCustomers" that touches 27 places at once.

TheSoftwareGuy 4y ago
To counter, any merge request with more than 2-3 commits is probably too big anyway
- ricardobeat 4y ago
  Not a fan of those arbitrary limits. It's all about being able to quickly understand the changes and their reason to be. If splitting the updates in smaller increments help, then so be it, and I'll take ten tidy small commits over two large ones any day.
  - morelisp 4y ago
    PR guidelines - Git best practices generally - are one of those situations where you must provide concrete guidelines but also never, ever make them a hard rule. If you don't have any you'll get endless "fix" "oops" +9876/-1234 changes, and if you make them a hard rule you'll never get anything useful done as people spend all day trying to please the aesthetic preference of a team lead who probably hasn't written a more than a single two line commit in years.
- wizofaus 4y ago
  Huh? The number of commits is irrelevant - the number of changed lines/ files is what matters. 20 commits can result in a couple of lines in one file changing (I've seen it happen) and 1 commit can have 100s of files changed (usually when some commonly used symbol has been renamed).
4y ago

james-skemp 4y ago

Based upon username will assume author shared it here: You've neglected to state what commit messages do matter, unless you think none do. In my experience, commit messages only don't matter if the code is never used beyond the first creation. Once you have to maintain the code, commit messages absolutely matter. Does it need to include the granular details mentioned in the article? No. But commit messages help determine what commits should be reviewed during maintenance (including adding new functionality). (I also experienced a touch of cosmic fear while reading the article, thinking about someone who might rebase or squash every commit, leaving only one commit for an entire repo.)

gspencley 4y ago

It wholely depends on what you are hoping to get out of the commit messages. I don't want to see the local commit history of individual developers in the commit history of any shared branches (be it mainline branches or shared development branches). What I do want to see is a history of pull request merges. I don't care how they are formatted (and this is often done automatically) but it matters that if I want to check out a historical changeset that I can. This is particularly useful when there are regression bugs that managed to slip through the QA and automated testing processes and it is unclear what caused them and when. It is nice to be able to go through the commit log and identify suspect work items, check out the commits during that time and see what they changed. How you format the commit messages isn't that import as long as your pull-requests are squashed-merged (to suppress local dev workflow commits that aren't relevant to the team) and the commit messages facilitate doing that with something that links back to a work item.

afterburner5 4y ago
Louder, for the purists at the back!

einpoklum 4y ago

> Commit messages are probably one of the worst places for documentation They're a bad place for documenting the repository for users. They're about the sole place to document what's in the _commit_... > and a common source of bikeshedding. You can bikeshed anything if you like. But I'll grant the author's claim that bikeshedding the exact format convention of commit messages is excessive. If someone wrote "Added feature X" as opposed to "Add feature X" - yeah, that doesn't really matter. On the other hand, if the first line of a commit message is extremely broad and vague, this makes it difficult for the developer browsing the commit history in a one-line-per-commit view. > Adding in information about what files have changed doesn't make sense It can makes sense if it's essential to the commit, e.g. "Moved `foo` from `file1.h` to `file2.h`". But TBH - this is bikeshedding. > this information is more easily stored by looking at the diff Ah, but the whole point is that you want to _avoid_ looking at the diffs of many commits. > Information about why and how often have better homes. Nope. > There's the code review history, the bug tracker These are not part of the VCS commit history, and may not even exist at all. > the code comments So, we want to put commit comments as actual comments now? No. > and the actual documentation. No. The actual documentation is: 1. Intended for users of the repository rather than developers/maintainers of the repository. 2. Documents all commits up some release (or up to some commit). > Your commit message essays will probably be lost or munged anyway – squashed, merge committed, or rebased. So will our code... but the point is that, after such squashes etc., there is still a commit history for which it is important and useful to have commit messages.

steveBK123 4y ago

The worst commit message bureaucracy is the requirement to link to a story / feat|bug|etc classification and perfect message formatting or it gets rejected. My firm went through 3 different ticket systems in 5 years, including a round trip to Jira. Teams/apps migrated to different Jira projects, repos got split apart/merged, tickets were archived, etc. So the commit blocking requirement of having a link to the story ends up pointing to dead ends or stuff you may not have access to quite often. This is the kind of stuff that causes senior devs to commit less often, or to have an always-open "misc" ticket to book everything to, with a copy-paste ready commit message in the proper format to pass checks.

rvdginste 4y ago
As a team lead I insist on a link to a ticket for stuff that is related to a ticket. When moving to another ticket system, I insist either on keeping older projects on the old system, or alternatively on migrating old tickets to the new system and keeping the original references; the same way I insist on keeping history when moving from one source control system to another one. Also... why would a company go through 3 different ticket systems in 5 years? That must cost a lot and definitely is not gonna help convincing people to use it...
- steveBK123 4y ago
  hard to imagine, but many IT orgs are poorly run!

ptx 4y ago

> Your commit message essays will probably be lost or munged anyway – squashed, merge committed, or rebased. Yes, because commit messages do matter and rebasing/squashing is how you clean up your initial draft commits. (Merging doesn't lose or munge the commits.)

afterburner5 4y ago

I can see where the author's coming from. However, my approach for a PR might be a bit of a mix. Normally, I aim to make a PR be reviewable, commit by commit. However, in some cases, due to a semicolon missing (you get the point), or some instance where I'm being daft, or me bumbling in the dark trying to fix a piece of ancient, undocumented code, the history might end up being less than clean. The messages will always describe my train of thought in those scenarios, but the overall history wouldn't be cut and dry. I tend not to worry about that and generally just squash the commits when I merge, so that, on main, there's a single commit for a particular feature. That's an overall piece of work I did. If someone wants to dig into a feature commit by commit, they can typically check the PR out and do it that way, but in practice, I've rarely seen that happen, and if it did, it was more for the overall feature rather than any one commit. So, overall, it's not that commit messages don't matter, but rather that, while a pristine history is always nice to see, it's not always possible without unnecessary head scratching that generally just costs more dev time for very little benefit.

staticassertion 4y ago
Does anyone actually review PRs commit by commit?
- masklinn 4y ago
  When the history is designed for that, sure. Although having the review tool also designed for it makes this much more convenient and comfortable. Github, sadly, very much is not designed for that.
masklinn 4y ago
You know that you can edit the history in order to fold the small fixes and mistakes back into the commit they belong to right? It’s not an all or nothing situation. > If someone wants to dig into a feature commit by commit, they can typically check the PR out and do it that way, but in practice, I've rarely seen that happen Of course not, it’s a pain in the ass having to go back to the PR and trawl through a commits sequence you describe as essentially broken.

morelisp 4y ago

Rickard is just on a roll of absolute garbage lately. Why does this get posted?

LennyWhiteJr 4y ago

Commit messages don’t matter. In fact they matter so little that I'm going to write a blog post about how much they don't matter. Commit messages are probably one of the worst places for documentation and a common source of bikeshedding. So let me kickstart some more bikeshedding since there's not enough already.

eminence32 4y ago

I work at a large software company that has, for decades, operated without any commit messages whatsoever. When you get the days latest code in your workspace, you know what files are changed, but not why (and often not who). Has our company imploded? No. But you absolutely feel this lack of information whenever you wonder "hmm, why is this line of code the way it is". As we've transitioned to git, we don't have a universal culture of writing commit messages, and I wish we did.

epolanski 4y ago

Amen. My company has a fixation with it and yet no use. Zero. The only instance where it paid off was to include the jira task code in the second line of the commit, but this also has been short sighted and rarely useful because most discussion about PRs happens on slack and teams, not on Jira.

knodi 4y ago

why not just go back to svn...

einherjae 4y ago

Bait, please ignore.

davedunkin 4y ago

This sounds like the advice of someone who hasn’t worked in codebases mature enough to go through multiple source control system and issue tracking system changes. The commit message is the one piece of documentation most likely to survive. A commit message that explains why the change was made can be very valuable when the code review comments and bug report are no longer available.

subw00f 4y ago

Just write why something changed, not what, nobody will read the log like a book, they will just use blame. The rest is bs.

DSMan195276 4y ago

> There's the code review history, the bug tracker, the code comments, and the actual documentation. All of which are probably better places for real knowledge to be stored. The funny thing is that I've been through many of these systems in the past years, and each time we mostly lost all the previous PRs and comments, but all my commit messages are still there preserved in the history. These ideas are all a "better place" until it's suddenly all gone because it's not actually a part of your code history and can't easily be moved.

tuetuopay 4y ago

I wholeheartedly disagree. Bug tracker? It can change. Reviews discussion? The tool can change. You get the point. As an added pain point, I don't want to juggle different tools to get the whole picture about changes. I don't want to copy/paste a Jira ticket reference in my browser from my terminal to get the reasoning about the change. I don't want to copy/paste a bugtracker ID to get the reasoning about the change. Commit messages are here for a reason, and it is to document the change. I find them invaluable when digging through a codebase with plain git tools, tig, or the git integration of an IDE. Conversely, this is why I hate squashes of PRs of more than X commits. Just no.

groestl 4y ago
> this is why I hate squashes of PRs I like them because of the linear history, but the commit message should keep the explanation for _all_ the changes.
- tuetuopay 4y ago
  For this, I often configure repos to only accept "fast-forward merges", as to keep a linear history. The added benefit is increased by good splitting of commits as conflicts will be resolved commit by commit rather than the whole PR with a possibly huge conflict to solve.
usrusr 4y ago
But commit messages can also be too fine-grained, at least if you are not into the squashing game. And a level of conciseness that is valuable in commits might be a little too short for truly meaningful context years later. My preferred pattern is some "why" in the message, as a soft "should", and a external reference to some potentially longer and perhaps not so fine-grained ticket/story/bugtracker-id as a much stronger "should". That's where longer form prose has its place, or some media, and most importantly after the fact amendments without the hassle of history rewriting. And once that pattern is 80% established, even the emotional outlet of an occasional "whoopsie" message can be totally worth the cost, if it's actually "whoopsie (WHYJIRA-12345)" Anything occasionally gets lost. (some languages have surprisingly useful decompiles..) It's probably best if all approaches are taken in parallel. And taken reasonably well (as opposed to gold plating), enough to be workable alone in a pinch but decidedly not fully redundant. Comments, commits and out-of-band tickets all have their place and neither is a good substitute for the others. Allow them to complement each other, and strive for just enough overlap to make losses somewhat tolerable.

nix0n 4y ago

Is there some trick I don't know about, to quickly go from a source line, to the PR discussion? If there is, the PR discussion might be the right place for explanation, but if not, the commit message is still valuable.

masklinn 4y ago
> Is there some trick I don't know about, to quickly go from a source line, to the PR discussion? Assuming people are religious about putting the PR ID in the commit message, you might be able to relatively easily jump from the commit you found normally (e.g. blame-diving or via the log) to the PR. Whatever your tool might even be able to do the jump in one shot, though I think it jetbrains stuff it usually takes two (“open in > Github” from the commit, and from there click the reference to the PR). But obviously that means you did go through the commit message, and having had a good summary in the commit message would likely have saved you the trouble.

abrax3141 4y ago

I use selections from random poems as my commit messages in order to confuse the AIs of the future that intend to learn from them.

francisofascii 4y ago

This sounds penny wise, pound foolish. If I spend half a day tracking down a two or three line bug fix in a large codebase, you bet I will spend the extra minute it takes to make a decent commit message.

austinl 4y ago

I think titles of PRs matter, and at least for me, they're often identical to the commit message (either a one commit PR, or multiple commits git-squashed for one PR). I suppose it depends on your use case, one example is that I use these titles written by myself and co-workers to write beta release notes each week, which folks seem to really appreciate.

pjs_ 4y ago

Looking fwd to going viral multiple times on Hacker News over the course of the next few months with such irresistible blog posts as: - Don't be afraid to roll your own crypto - Why using string types for numeric data is actually a great idea - Let's put all the code in one really big function

becquerel 4y ago

The author's complaints could equally be applied to naming branches, but I suspect he would find it difficult to work if all of our branches were named 'a', 'bbbbb' 'seroiuwegonw' and the like. Without messages, commits are only identifiable by arbitrary and meaningless strings of letters and digits. This would make git bisect needlessly more difficult, if nothing else.

fdr 4y ago

I disagree with the author. Text explaining a "why" are often contemporaneous. To put it all in the source text would be too bloated and too prone to bitrotting into misinformation to be useful. To increase concision to the point where bitrot is unlikely loses useful contemporaneous detail. So, I prefer concise comments that are highly salient and unlikely to turn into misinformation, usually about key details on a mechanism where subtle mistake is more likely than the norm, and detailed commit messages on contemporary justification. Also, the author mentions the commit messages being "probably lost." I'm not sure what the author is doing to get themselves into that situation. I work on code bases with good commit messages. I use emacs's vc-annotate with regularity.

Tehnix 4y ago

This will largely depend on your workflow, but in a PR-based workflow, I've for a while now held the opinion that individual commit messages are useless to me in the history of the code, and that a squash with a final description + summary is the best way to go. There'll be cases where the following don't match, so let me explain what this is based on: - In our flow, a PR is small and is the unit of work that is guaranteed to compile/work (tested against master before merge) - Each individual commit inside the PR can be helpful for a reviewer, but the code should stand on its own and your commits (inside the PR) should not be a source of documentation - I have never been able to pick out a commit at random from non-squashed PRs, and be sure it will compile. Unless you're running CI locally before committing, you simply do not know - Spending a ton of time to create a nice history inside a PR is a waste of time, since throughout review or experimentation you will need to adjust work that you previously committed as if you had everything thought out - the alternative is aggressive history rewriting and force pushing which is very quickly a huge mess - Finally, it tremendously lowers the bar of what's required from each developer, which scales much better, when all you have to do is take extra care in the final title and description Now, most importantly, squashing PRs is tremendously helpful when digging around the code and having something like Gitlens explaining the changes: - Commits from a merge commit are on average a lie of the final reason, and very often something like adjusting formatting, fixing linting, which makes the original reason disappear as this was the latest change - Viewing the squashed PR title and description gives me so much more information and if I want to dive into the specifics, the PR itself is worth so much more than any individual commit message will be Again, this is something that fits with a specific workflow. If you're developing directly against master or similar styles, then obviously this won't suit you. --- The review and history part is actually something that is interesting to dive into for the importance of commit messages and what you and your teams expectations are. I'd recommend explicitly talking about this with your team :)

TrianguloY 4y ago

* more changes < feature/PD456 * more changes * more changes * changes < origin/feature/PD456 A week later: "what did I do here? Let me check the source code" (10 minutes of checking changes trying to understand what it does) No thanks, I prefer to at least write some minimal indications like * cleanup and tweaks < feature/PD456 * implemented feature, new test pass * added new test (now fails) * updated version to 1.2.3 < origin/feature/PD456

jscholes 4y ago

Do you know what doesn't matter? Articles about whether commit messages do or don't. What matters is the art of documenting things, somewhere, and that place should be the one that works for your team. If it's commit messages today, great. If that changes in the future, great. If it's somewhere else entirely already, also fine.

andosteinmetz 4y ago

Having worked with people whose commit messages are along the lines of "update function", my experience has been that when you're trying to find where a bug was introduced, it's quite helpful to review (good) commit messages to quickly get a sense of what concerns a commit was addressing, and what code it's likely to have touched. Speaking for myself, I also find that writing a good commit message is useful in helping me think about what work I've just completed and whether the changes I'm committing form a logical group. Granted, there are all kinds of workflows and I can vaguely imagine some in which commit messages are redundant, but still, I don't think it makes sense to generalize the statement.

tildef 4y ago

I write descriptive commit messages because the code I check in is likely to contain a bug. This bug tends to be discovered a couple of years after I worked on the code. By linking my commit message to an issue and having a good explanation for why I've done what I've done, I can easier get into the mindset I had when I committed the buggy code. I find my life gets less stressful this way. I do agree that just regurgitating the files/classes/methods a commit touches isn't very useful. I'll consider ceasing to write "good" commit messages when I'm confident the code I check in doesn't contain any bugs.

rvdginste 4y ago
> I'll consider ceasing to write "good" commit messages when I'm confident the code I check in doesn't contain any bugs. Please don't. As much as it is useful to fix buggy code at a later point, it is the same useful to prevent introducing buggy code at a later point! Never saw some code that looked funny at first sight, and that you considered 'fixing', then checked the commit messages and understood why the code was written the way it is? Fixing it, would have meant introducing a bug.
wizofaus 4y ago
If every PR you put up is "likely" to contain a bug, you're doing it wrong.

pierrebai 4y ago

I grep commit history from time to time to find when something was done. It is not useless. I also compose the pull request description from concatenation and editing of the multiple commit messages. Good PR description is essential for... good code reviews. So that the reviewer knows where you are coming from. Sure, there is also code comments, but have a good PR message preps you to read the code., And that good intro comes from commit messages.

zzyzxd 4y ago

Out of curiosity, I took a look at the author's commits on github[1] just to see how bad a person's commits can be when they think "Commit Messages Don't Matter" ... Surprisingly, most of his commits were not bad at all. In fact, most of them started with a clean, short, one-sentence imperative summary in present-tense, followed by multi-line detailed explanation when needed with short line length. They are a lot better than the average commit quality I see in many FOSS projects. 1. https://github.com/search?q=author%3Ar2d4 https://github.com/search?q=author%3Ar2d4

deleted 4y ago
[deleted]

TheChaplain 4y ago

I follow the Conventional Commits specification; https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ It's actually quite good and if one takes 30s to write a little more descriptive message of what has been done, it'll help the next person.

rvdginste 4y ago

I think people who think that commit messages don't matter, should be forced to maintain a code base written by colleagues of the same opinion for the next 5 years.

sys_64738 4y ago

Commit messages should match the bug ID and synopsis of the bug the commit fixes. Failing that it should be a short description (80 chars or less) detailing the functional change.