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
@craigmaloney Know of any sites that showcase best practices on this?
@bthall No, but I know of one that is demonstrating the anti-pattern. :)
@craigmaloney YES! 💯%
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.
@superruserr Ah, very cool. Thanks for pointing me to this.
@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 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 sf.net 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... ¯\_(ツ)_/¯
The social network of the future: No ads, no corporate surveillance, ethical design, and decentralization! Own your data with Mastodon!