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 @zigg Oh, heck yes. You can't automate documentation. Not changelogs, not API definitions, not function descriptions. People should stop trying to get out of writing with tooling and take the time to communicate well.

@craigmaloney Know of any sites that showcase best practices on this?

@bthall No, but I know of one that is demonstrating the anti-pattern. :)

@superruserr @TheDoctor slight irony that the project doesn't have a file called Changelog. :eyethink:

@craigmaloney @TheDoctor Hmm...

Are change logs and release notes the same thing or somewhat different ?

I may be confusing terminology on my end with what you are looking for.

@superruserr @TheDoctor Was in part because the release notes are under NEWS and not where I thought they would be.


Each time a change is made in a PR, you add a newsfile like below describing the change made in the PR:

PR_ID.ignore if the change is minor and not worth reading in the public space. ie a change involving fixing newlines.

PR_ID.bugfix if the change is a bugfix.

PR_ID.feature if it's an added feature.

PR_ID.remove if something is taken away

And so on.

Then when a release is made towncrier collates them all into one document, or concatenates on top of existing release notes.

@craigmaloney I am terrible about this despite knowing it is important. I often get caught up in fixing something and then forget what I actually changed.

I HATE it when an app’s changelog is just “Thanks for using our app!” EVERY SINGLE TIME.

@craigmaloney Obviously everyone will agree with that. That's not the issue. The issue is how to make writing release notes more practical.

@fortuna Sure. it begins by pausing for a moment and reflecting on what the release contains. Making the pause happen is the hard part since developers don't tend to want to pause. Until we get that pause and the moment of reflection there's no practical way to make it better.

@craigmaloney I believe that works well for single-person or small project but it's challenging when you need to scale to many changes and collaborators.

In that case release notes will scale better if you maintain running notes, updated when important changes happen by the authors themselves.

@craigmaloney Right, let me know what *USER FACING* changes there are.

@Canageek Ugh, you're right; it's even worse than a git commit log.

@craigmaloney What is your opinion on snarking at other software in your changelogs? (Search for OLEX2. Also yes, this software is 40 years old and still updating)

@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!