Oh boy, I absolutely hate this stupid trend of not writing changelogs anymore! Why the fuck would one seriously consider it to be a viable option to just let some shitty bot spew all merge requests on a goddamn GitHub release?! First of all, these merge request titles suck balls. The order of the changes in this “changelog” is completely random (well, probably merge time, which is as useless as the dick on the Pope). They are not grouped by anything at all. Additions, changes, removals, deprecations, etc. randomly mixed up in one giant list. And then “Add feature X”, seventeen kilometers further down “Revert ‘Add feature X’”. Fuck you! Don’t include this shit in the first place!
Fits absolutely perfect in the pattern of rapid decline.
I must rip out all dependencies as soon as possible whose maintainers just don’t give a shit.
@lyse … I am literally writing a blog post about changelogs at this very moment … 😂 I am certainly adding the “‘add X’ and then later ‘remove X’” to my list of DON’Ts. 😅
@lyse This is the draft so far, let me know what you think: https://movq.de/blog/drafts/changelog/POSTING-en.html
@movq Hahaha, great timing! :-D I love your article and agree with almost all your points.
On the AI changelog part, though, I’d rather recommend to just not have a changelog at all.
Another important thing for me is the deprecation notice section. What do I need to look out for in the future? Should I start to migrate to another API soon? Even right now? Or does it have time?
While going through these terrible GitHub release pages, I also found these “New Project Contributors” sections (yeah, for that, they found the time to make a section) annoying. Don’t get me wrong, sure, credit where credit is due. But come on. Soooooo much space for an inefficiently formatted (and also unsorted) list. At least it was easy enough to skip over it.
And then, there are also these changelogs or rather notice documents in general that are infested with multicolored emojis all over the place. My brain’s spam filter kicks in and shoves everything to /dev/null immediately. It’s especially a thing at work.
In my previous work project, we also used the Keep A Changelog Format. That was great. You wouldn’t believe how often I resorted back to that document. At least twice a week, often several times a day. I was very glad that we put in this effort. Of course, writing the changelog took its time, but it was worth every minute and more. Reading a many months old item, it was immediately clear. I was our best customer in that regard.
Now, it’s just the same auto shitshow with MR titles in a rolling date-versioned release scheme. It’s just our team who has to deal with that, though. I think I’m the only one who is not a fan of it.
@lyse Thanks!
On the AI changelog part, though, I’d rather recommend to just not have a changelog at all.
I’m afraid that ship has sailed. You can rest assured that someone who uses AI/LLMs for their code (which is almost everybody at this point) will most certainly also use it for changelogs.
I actually considered not mentioning AI output at all, because this just opens a huge can of worms … 😞
While going through these terrible GitHub release pages, I also found these “New Project Contributors” sections
Yeah, they play on a nerd’s pride.
Now, it’s just the same auto shitshow with MR titles in a rolling date-versioned release scheme. It’s just our team who has to deal with that, though. I think I’m the only one who is not a fan of it.
I’ve found that this whole situation is much worse at work than it is in the Free Software world. At work, it’s literally work and hardly anybody actually cares. We still don’t have all people convinced that writing good commit messages or using good branch names is worth the time. It’s … oh god, no, I’m going to stop here, this is bad for my mental health. 😅
Suffice it to say, all release notes at work are now AI-generated. Nobody gives a fuck.
@movq You may want to include another antipattern to avoid in your article:
- bump $same_dependency from 1.0.0 to 1.0.1
- bump $same_dependency from 1.0.1 to 1.0.2
- bump $same_dependency from 1.0.2 to 1.1.0
- bump $same_dependency from 1.1.0 to 1.2.0
@movq I just ran across another thing. At least I personally couldn’t care less about CI infrastructure changes. Whether they’re using github action a or b or c or version v or w, it is not of my interest. At all. (It might be useful to estimate the supply chain attack risk, though.) If the maintainers want to include them in the changelog – and there are probably people to whom this information is crucial – it’s probably best to document CI infrastructure changes in their own section.
@lyse Oh god, yeah. In other words: Devs need to think about who their target audience is. 😐
Updated draft: http://movq.de/blog/drafts/changelog/POSTING-en.html
I’ll probably publish this later today. Or maybe not at all. It’s one of those topics that might cause outrage because I’m getting it all wrong. 🤪