Plague Morosely πŸŽƒ
Follow

Developers:

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.

Β· Web Β· 0 Β· 103 Β· 113

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

@andrewt @craigmaloney @zigg

Maybe writing wouldn't be so hard for developers if they bothered to take a few English classes?

@starbreaker @andrewt @craigmaloney @zigg Depends on the classes; I don't mind broken syntax too much if the ideas are presented in a reasonable order and things are named clearly. Getting hung up on grammar is where we get code that's linted to heck but doesn't work.

@andrewt @craigmaloney @zigg I'm not expecting Pulitzer-prize winning prose from developers. I just want to read a changelog without this clip playing in the back of my head.

youtu.be/a0x6vIAtFcI

@craigmaloney being an avid reader of changelogs, I stick to that rule myself. Today I prepared this one: gitlab.com/iosa/iosacal/blob/m

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

@craigmaloney

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 my thought process:
1 this variable needs a null check, add that
2 fuck lint
3 fuck lint
4 fuck lint

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

@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? shelx.uni-goettingen.de/change (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.

@craigmaloney

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.

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

@craigmaloney
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
Octodon

Octodon is a nice general purpose instance. more