Friend to friend: When you make a release please take a few minutes to make a human-readable changelog of what has changed since the last release?

Your commit-messages are not a changelog.

Let me re-iterate:

Your commit-messages are _not_ a changelog.

A changelog allows me to follow what you were thinking between releases.

A commit log shows me your keystrokes between releases.

I need to know what you were thinking.

Thank you.

@craigmaloney What about phrasing git commit messages as explanations of your thinking?


@gittaca That is one possibility but I've seen my own commits turn from well-thought out prose to "Checkpoint" depending on the stress of the moment and the cognitive load to overcome it.

And as someone who has had to review a commit log to see what to put into the change log I've also seen instances where a singular thought is spread out over multiple commits.

So while it might be good for disciplined developers / teams I'd submit that you still need a changelog to surface that prose.


I see a changelog as a compromise / bridge technology to eventually reach: explanatory commit messages, plus release blog post for general audience :-)

@gittaca I disagree: I think the changelog bridges all of those together so I only have one-stop shopping for what has changed since the last release. It means I don't have to hope that the blog post is still up / hasn't moved locations / is moribund, and it ensures that I'm not having to do some git -fu to figure out release tags.

So a bridge, but one that I find necessary to help those not intimately familiar with the project.

Agreed, but why should a blog post be inherently more prone to being down, moving locations, etc.?

@gittaca Ask anyone who has moved from to another platform, or places where they no longer run a blog. There's a lot of reasons why a blog post will go moribund.

But more reasons for the blog than for a changelog? I started only after GitHub & GitLab Pages were availbable, so... ¯\_(ツ)_/¯

Sign in to participate in the conversation

The social network of the future: No ads, no corporate surveillance, ethical design, and decentralization! Own your data with Mastodon!