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.
@craigmaloney being an avid reader of changelogs, I stick to that rule myself. Today I prepared this one: https://gitlab.com/iosa/iosacal/blob/master/docs/whatsnew.txt
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.
@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.
@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.
@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.