Ugh. One of my pet peeves is the generation of release notes from commit messages. Commit messages and PR descriptions have a different audience (i.e. contributors) from release notes (i.e. users).<p>For example, take a look at ESLint's autogenerated changelog [1]:<p><pre><code> 67c0074 Update: Suggest missing rule in flat config (fixes #14027) (#15074) (Nicholas C. Zakas)
cf34e5c Update: space-before-blocks ignore after switch colons (fixes #15082) (#15093) (Milos Djermanovic)
c9efb5f Fix: preserve formatting when rules are removed from disable directives (#15081) (Milos Djermanovic)
14a4739 Update: no-new-func rule catching eval case of MemberExpression (#14860) (Mojtaba Samimi)
7f2346b Docs: Update release blog post template (#15094) (Nicholas C. Zakas)
fabdf8a Chore: Remove target.all from Makefile.js (#15088) (Hirotaka Tagawa / wafuwafu13)
e3cd141 Sponsors: Sync README with website (ESLint Jenkins)
05d7140 Chore: document target global in Makefile.js (#15084) (Hirotaka Tagawa / wafuwafu13)
0a1a850 Update: include ruleId in error logs (fixes #15037) (#15053) (Ari Perkkiö)
47be800 Chore: test Property > .key with { a = 1 } pattern (fixes #14799) (#15072) (Milos Djermanovic)
a744dfa Docs: Update CLA info (#15058) (Brian Warner)
9fb0f70 Chore: fix bug report template (#15061) (Milos Djermanovic)
f87e199 Chore: Cleanup issue templates (#15039) (Nicholas C. Zakas)
</code></pre>
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.<p>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.<p>[1] <a href="https://github.com/eslint/eslint/blob/master/CHANGELOG.md" rel="nofollow">https://github.com/eslint/eslint/blob/master/CHANGELOG.md</a>
In summary: Henceforth releasenotes will consist of mostly automated dependency bumps and the same commit messages that you can also see in the commit history.
Nice. Shame the automatic changelog doesn't include commits that didn't go in via PR though. (Not possible to exclude locally rebased or squashed PRs I suppose, but all straight merges and anything done via GH UI surely covers most usage.)
Hey all, I'm the PM for this launch feel free to ask any questions<p>We are also collecting feedback in this discussion<p><a href="https://github.com/github/feedback/discussions/5962" rel="nofollow">https://github.com/github/feedback/discussions/5962</a>
Automation like this is definitely a helpful first step for maintainers who want to prepare good release notes.<p>I wrote a provider-neutral guide for using git itself to help automate the preparation of good release notes, and also provide some more specific advice on how to make them worth reading:<p><a href="https://drewdevault.com/2021/05/19/How-to-write-release-notes.html" rel="nofollow">https://drewdevault.com/2021/05/19/How-to-write-release-note...</a><p>This might offer some advice useful to those trying out this new GitHub feature, which can take the place of the git shortlog step I described here.<p>Disclaimer: I represent a platform which competes with GitHub
Automatic change log generation is great, it's always a pain to do this. Hopefully the actions API makes it easy to output notes with better organization, like grouping conventional commits.<p>One more thing I'd love is a timeline entry/comment on relevant issues/pull requests to say that it was included in a specific release. I know we can do this via actions, but there's so many maintainers and consumers of smaller open source repos that would benefit.
It would be nice if the release process also added the hash of any built binaries to a distributed append-only log. That's sort of the approach that sigstore and rekor were made for, to enable Binary Transparency, and they're already being used in the Arch Linux package ecosystem:<p><a href="https://github.com/kpcyrd/pacman-bintrans" rel="nofollow">https://github.com/kpcyrd/pacman-bintrans</a>
I think the fundamental issue plaguing virtually all forms of automatic release note generation boils down to the mismatch of audience. Commit messages and even pull request titles are tailored to be read and understood by other maintainers and contributors, who are likely to be familiar with internal details of the project. Clear and concise communication for this audience might mean using more specialized jargon or referencing implementation details.<p>By contrast, release notes are meant to be consumed by a much wider audience, who are chiefly concerned with the externally visible aspects of the project. Communication tailored to other maintainers (e.g. commits and PR titles) is rarely also optimal for this broader audience. This is why commit-based generated changelogs have a bad reputation: commits are meant for contributors—not customers—and thus tend to be useless.<p>This also explains why a good, dedicated CHANGELOG.md is usually so effective: unlike commits or PRs, it affords contribution authors a separate place to write for a broader, different audience. Another nice property of this method is the notes themselves within the CHANGELOG.md can be collaboratively reviewed and edited right within the context of the PR. This is a very helpful mechanism to ensure that release notes are high quality and to distribute the burden of writing release notes to those most familiar with the changes (as opposed to the person creating the release).<p>I think the ideal scenario is that on a per-PR basis, the "external" release notes are automatically scaffolded from existing metadata such as commits or PR titles (or even sophisticated means such as identifying which packages have changed or knowing if a breaking change has occurred as a result of type interface changes) which are later refined/edited during PR review. I think it would also be great if GitHub Releases themselves could go through a review process akin to PRs in order to help ensure high quality and facilitate collaborative writing of release notes.
> If you are automating releases with GitHub Actions, we have an API that you can use in your workflows to integrate the new Automated Release Notes feature right into your existing actions pipeline.<p>I can't seem to find the documentation about integrating this with Actions<p>But I am excited to finally be able to stop maintaining my custom auto-release-changelogs action <a href="https://github.com/Trinovantes/action-automatic-release" rel="nofollow">https://github.com/Trinovantes/action-automatic-release</a>
This is fairly close to what we generate for our change log, closed issues and closed and merged pull requests keyed by release milestone. Release notes are separate though, and written by hand.<p>Maven plugin, if you're interested<p>[1] <a href="https://github.com/heuermh/github-changes-maven-plugin" rel="nofollow">https://github.com/heuermh/github-changes-maven-plugin</a>
"GitHub is where developers come to learn and celebrate what’s new in open source, and where maintainers share, collaborate and celebrate their community’s work."<p>I thought GitHub was a closed-source SAAS by Microsoft.