PS. I do appreciate the effort btw! Better release notes in general is definitely something to strive for, and I hope you'll keep a tight pulse on how this affects what release notes on average look like and whether they get better, and of course how they can get even better :)
What about dropping the ones that don't fix bugs (assuming they are part of ongoing work), replace the ones that fixes the bug with the description of the bug (and a working link!), and categorize them based on the tags of the bug (defect, feature request, etc...) so you would automatically get a list like:
New Features:
"title of feature request 1"
"title of feature request 2"
Bugs fixed:
"bug1"
"bug2"https://docs.github.com/en/repositories/releasing-projects-o...
I think part of the problem is also that in theory, it's already possible to write a good changelog as well — but of course, what's relevant is what happens in practice :)
Of course, not every project can manage to write such a thoughtful post for every release, but if Mr. Graham can do it for something as sprawling as KDE, then can sure at least try.
so true, I even wrote a small script to drop the obvious cruft:
https://git.proxmox.com/?p=pve-eslint.git;a=blob;f=debian/sc...
(I know I could make that shorter, but I explicitly split some sed statements to make it easier to read, it's a few lines only anyway)
I meant that a good 'why' commit subject that gets propagated to release notes is more likely helpful to an end user - ooh nice yes I have had that problem, cool it's fixed, I don't care exactly what fixed it.
Subject: Reason this commit exists ('why' e.g. 'Fix syntax error navigating to /about')
Message: Explanation for code, why it's correct fix, background etc. ('how' I suppose)
Code: ... (that which I've called 'what')
Well, you're just wrong then. These aren't code comments. They're commit summaries. They exist only to answer the question "what?"--tersely. Because they're meant to help you pick out the right one when you're looking at a list of them and don't have the entire diff on the screen. But I don't think we're even in conflict here, because your example ("Fix syntax error[...]") actually shows this. I don't know why you keep calling that "why". It's "what". Any way of thinking of this as answering the question "why" (such as "why am I making this change?") is incidental. You're identifying which commit this is. That's a "what".
> Code: ... (that which I've called 'what')
What? No, code is never "what", whether you're talking about commits or you actually are working on the code and comments themselves. Code is "how", identifiers/names are "what", and comments and commit messages are "why". See my other reply to Vinnl about how weird it is to mix up "why" and "how" in the same breath.
The code is what I'm committing; the subject is why I'm committing it; the message is (a continuation of the subject's why and) a description of how I arrived at it, how it applies to the problem, etc.
Of course it can be phrased differently ('code is how I'm solving the problem; subject is what problem I'm solving' etc.) - I really don't think it matters much what we call them. Point is that, IMO, the subject especially and to a large extent the rest of the message should focus on the reason for the change, not re-describe the change itself, and framed in a way that's not necessarily end-user oriented but is certainly more detached from the implementation in code.
Less ambiguous than what/why/how then: code - the change; subject - the reason for it; message - the explanation of it.
Example from their other reply:
> Message: Explanation for code, why it's correct fix, background etc. ('how' I suppose)
Uh, what? It doesn't make any sense to (correctly) refer to this as "why" at first and then conclude that it must be "how"? Just stick with "why".
To repeat, first referring to the commit message body as why but then concluding you should call it how (because it can't be "why" since you've already decided that the summary is your "why" (which can't be "what" because you want the code to be your "what"))... is the kind of internal inconsistency that should be all the evidence you need to abandon this campaign to insist on using this terminology.
And speaking of inconsistency and insistence: if you truly think it doesn't matter, then there's no reason to insist on defending it. The only reason to do so would be if you didn't actually believe that it doesn't matter, and you just said it didn't because it seemed like a convenient way to argue that the weirder nomenclature is acceptable. But again, if it truly doesn't matter, then you'd have no problem letting go of that, right?
> you need to abandon this campaign to insist on using this terminology.
Sorry, who's insisting on it? I just said it doesn't matter what we call it, what terminology we use, just what we mean (and practise).
> argue that the weirder nomenclature is acceptable
I have no idea what you're talking about, taken as words alone they're ambiguous, yes, and can be used in different phrasings that make the single words apply to different things; as I demonstrated.
At least 'add missing indentation' is a few steps better than 'changes', or 'fixed', or dozens of commits with 'WIP' as the commit message.
We have a workflow that will only add to the release notes PRs that have the "Add to changelog" label which works okay, but sometimes you do have to decide who you want to address your PR title to.
For example, take a look at ESLint's autogenerated changelog [1]:
I'm reading release notes to get a feel for how the new release might impact me. This takes so much time to scan, because there's so much useless cruft (to me, as a user) I have to ignore.What's worked very well for me is to simply have an "I updated the changelog, if applicable" entry in my PR template checklist. Then when I cut a new release, I simply add the release date above the release notes currently listed under "Unreleased", and they'll list all relevant changes, reviewed during the pull request to verify that it is relevant to users.
[1] https://github.com/eslint/eslint/blob/master/CHANGELOG.md