I don't know who the intended audience of the release notes is, but it's not end users of this package like me. In the v6.0.0 notes there's no indication at all of why there's a major version bump, and what's incompatible with the 5.x series (if anything--perhaps you're not using semantic versioning).
There is, however, plenty of information that's completely useless to end users. For example:
-
'fix/typo-overridden-word' and 'fix:typo error in comments': None of the changes in these two PRs are user visible, and they don't affect the operation of bcrypt in any way at all. It's a waste of users' time and attention to be listing these in the release notes.
-
'Prepare for v6': As an end user, I'm entirely unsurprised that you would have to do some preparation for a release, so this entry isn't news to me, and it doesn't give me any user-actionable information to change or check anything. If this entry were left out, it would merely save end-user time and attention.
Probably more of the entries are unnecessary, but I don't have time to investigate each one.
Good release notes should tell end users only about things that can affect them. One way to think about it is to examine each point and say, "What decision or action are we asking the end user to make based on this point?" (That might be, "consider using a new API," "replace calls to obsolete APIs," "mark the issue about security problem X as resolved if you're tracking it," etc.)
I don't know who the intended audience of the release notes is, but it's not end users of this package like me. In the v6.0.0 notes there's no indication at all of why there's a major version bump, and what's incompatible with the 5.x series (if anything--perhaps you're not using semantic versioning).
There is, however, plenty of information that's completely useless to end users. For example:
'fix/typo-overridden-word' and 'fix:typo error in comments': None of the changes in these two PRs are user visible, and they don't affect the operation of bcrypt in any way at all. It's a waste of users' time and attention to be listing these in the release notes.
'Prepare for v6': As an end user, I'm entirely unsurprised that you would have to do some preparation for a release, so this entry isn't news to me, and it doesn't give me any user-actionable information to change or check anything. If this entry were left out, it would merely save end-user time and attention.
Probably more of the entries are unnecessary, but I don't have time to investigate each one.
Good release notes should tell end users only about things that can affect them. One way to think about it is to examine each point and say, "What decision or action are we asking the end user to make based on this point?" (That might be, "consider using a new API," "replace calls to obsolete APIs," "mark the issue about security problem X as resolved if you're tracking it," etc.)