7 ms·
The purpose of a git commit message is to answer the question “why does this commit exist?” That is the principal question you should be answering when you type
by teeray 4y ago
The purpose of a git commit message is to answer the question “why does this commit exist?” That is the principal question you should be answering when you type `git commit`. This is the question you will be asking yourself when you find that commit in `git blame` or if it shows up in `git bisect`. Try to help your future self out.
The changelog, on the other hand, answers the question “why does the customer care about these changes?” It could be the same reason as why the commit exists, but the question is different. If the customer doesn’t care, maybe it doesn’t even need an entry. Maybe why they care is slightly different than the reason the commit(s) exist.
This is why I advocate for a hand-updated CHANGELOG.md. It’s a very small amount of writing that forces developers to consider how their PRs will impact customers that an auto-generator will never be able to do well.
- RustyRussell 4y agoWe autogenerate our CHANGELOG.md extract from Changelog-[section] our git commit messages (Release Captain massages them if necessary), and have a GH bot which checks that you have a Changelog- note somewhere in your PR commits (can be Changelog-None: ....). This avoid merge hell on the CHANGELOG.md file.
- Ologn 4y ago> This avoid merge hell on the CHANGELOG.md file. Right, if you don't do something like this you can be in merge hell very quickly...
- plorkyeran 4y agoSetting `CHANGELOG.md merge=union` in .gitattributes mostly eliminates spurious merges conflicts on the changelog.
- jmmv 4y agoOh wow, thanks for the tip! Had no idea this existed.
- RustyRussell 4y agoMe too! Awesome, thanks!
- cuteboy19 4y agoDoesn't make sense to automatically do this, some changes can be mutually exclusive
- ChrisMarshallNY 4y agoI do hand-updated CHANGELOG.md files, for all my projects. Sometimes, my Git commits can be kind of verbose (and I'll occasionally put in smartass comments). I wouldn't dream of mining my Git logs for CHANGELOG entries. Actually, I hand-run many things that a lot of developers automate. Part of it is because I have control issues...
- icedchai 4y agoA couple jobs ago, I was at a company that had a "mandatory" squash / rebase / merge workflow so history would be clean. On top of that, they forced all their developers to update a change log as part of the merge. That file was a source of contention / merge conflict for nearly every PR, often requiring additional rounds of rebasing. On top of that, it was full of information that could've been gathered from the git log. Big waste of time, in my opinion.
- ChadNauseam 4y agoWe had something kind of similar, but designed to avoid merge contention. We had each PR include a randomly-generated number, and a `changelogs/` folder where you could add a `${number}.md` that was either blank or had a message that would be added to the changelog. After you made the PR, you could run a bash script to edit the PR to contain the number and generate the `${number}.md` file. It felt kind of silly and I don't know if anyone actually looked at the changelogs, but it took 2 minutes out of my day and worked well.
- ArrayBoundCheck 4y ago> The purpose of a git commit message is to answer the question “why does this commit exist?” Why? Every time I have asked this people say because you'll search the logs (which I have never done in my life) or because "it's good practice"
- fraudsyndrome 4y agoDoesn't mean others are in the same boat as you. The team I work on frequently write detailed commits to the point where I can (and have several times) successfully searched information from years ago on a block of code with the ticket number and the developers (even myself) reasoning at the time. Maybe it depends on the project but I've found myself doing this so often that I won't stop, it's such a small task that has given me so much benefit. If it doesn't help anyone then nothing was lost.
- ArrayBoundCheck 4y agoWhy are you searching a year or more back? Is this using git blame?
- shakna 4y agoTo explain why a certain block of code exists. When the code came into existence is rarely that important. You just want to know why. Why does the code fence against a particular circumstance you didn't think should be possible? Why does it call out to something you think is unrelated? Those questions can be answered by a proper commit message.
- ArrayBoundCheck 4y agoI set a breakpoint and run the test suite for that answer
- fragmede 4y agoThat answers what the code does, but not why it does what it does.