Git log is not a changelog • Hacker News Board

Re: Git log is not a changelog

#11

Post by GauntletWizard » Sat, Jul 16, 2022, 11:00 PM UTC

The missing part of this is filtering git history with "git log --first-parent", but that only works if your repo has good a) merge commit messages and b) hygiene in creating your merges so that your "Pretty" history is on branch 1.

On the other hand, it takes a lot of discipline to make the second branch useful at all. If you constantly make short commits with messages like "stuff", why bother keeping them in the repo at all? There's a ton of junk you don't need in the typical code review, and making it useful requires... Discipline.

Re: Git log is not a changelog

#12

Post by Karellen » Sat, Jul 16, 2022, 11:04 PM UTC

That depends what you mean by a changelog.

According to the GNU coding standards, which have been used for decades for a large amount of the core software on a Linux system, what you should put in the changelog looks quite a lot like a good git commit log would look like[0]. And Linux currently uses the git log as the changelog, and IIRC had a similar format in the pre-git era.

> The changelog targets your users. It must answer questions like:

> "What cool new feature is in this version?"

> "Is this annoying bug fixed?"

> "Is it safe to upgrade, or do I need to adjust my code/workflow to this new version?"

To me, that sounds like what a lot of projects would call "release notes" or (per GNU) "NEWS file"[1], not the changelog.

[0] https://www.gnu.org/prep/standards/standards.html#Change-Log... [1] https://www.gnu.org/prep/standards/standards.html#NEWS-File

Re: Git log is not a changelog

#13

Post by difosfor » Sat, Jul 16, 2022, 11:18 PM UTC

sss111 wrote: post #3

use https://www.conventionalcommits.org/en/v1.0.0/ , it has extensions that can autogenerate a nice looking changelog.

Yeah, at work we combine that with https://semantic-release.gitbook.io/semantic-release/ for changelog generation and continuous deployment to NPM. It takes some getting used to, but I like it.

Re: Git log is not a changelog

#14

Post by teeray » Sat, Jul 16, 2022, 11:19 PM UTC

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.

Re: Git log is not a changelog

#15

Post by taveras » Sat, Jul 16, 2022, 11:25 PM UTC

I find that many programmers are hyper-focused on writing automation for things that feel like a chore. This thinking has its purpose, but it’s almost an addiction.

For these folks, putting deliberate effort into change logs, release notes, and documentation feels wasteful.

My hunch is that this is due to a missing feedback loop: we are unlikely to get feedback about documentation, and more likely to get feedback on our project’s code.

My own writing improved after a past project had a strong feedback loop with my documentation’s intended audience. This has been so damn rare in my career, that it’s never surprising when I meet programmers who are uncomfortable with technical writing.

Re: Git log is not a changelog

#16

Post by mikewhy » Sat, Jul 16, 2022, 11:34 PM UTC

At work we squash and use standard-version to create a generic change log, then have a script that ingests that change log and goes to the PR to grab any associated tickets, screenshots, and release notes the developer may have written. The body of the PR is split into sections (just using markdown headers), so there is control over what goes into the release notes.

A git log is not a change log, sure. But PRs can contain a lot of useful information.

Re: Git log is not a changelog

#17

Post by RustyRussell » Sat, Jul 16, 2022, 11:45 PM UTC

teeray wrote: post #14

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 abo…

We 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.

Re: Git log is not a changelog

#18

Post by quickthrower2 » Sat, Jul 16, 2022, 11:59 PM UTC

git log let’s you check if you might be missing something from the change log (aka release notes) though.

Or if you didn’t actually release something you thought you did.

Re: Git log is not a changelog

#19

Post by ChrisMarshallNY » Sun, Jul 17, 2022, 12:49 AM UTC

teeray wrote: post #14

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 abo…

I 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...

Re: Git log is not a changelog

#20

Post by Ologn » Sun, Jul 17, 2022, 1:32 AM UTC

RustyRussell wrote: post #17

teeray wrote: post #14

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 abo…

We 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.

> 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...