14 ms·

A new public beta of GitHub Releases

125 points by mrzool 5y ago

heuermh 5y ago
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. Maven plugin, if you're interested [1] https://github.com/heuermh/github-changes-maven-plugin https://github.com/heuermh/github-changes-maven-plugin
krono 5y ago
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.
- arve0 5y ago
  …which is nice, when the master is not tagged and you’re trying to find out “does this release include the bug fix in pr #123” (without cloning and/or jumping between tags/branches).
  - krono 5y ago
    There's already a "compare" selector on the current/old releases page that lets you do just that with two clicks.
    - arve0 5y ago
      Thank you, that is useful, but basically same as "jumping" between branches. @pronik's reply was spot on, viewing the merge commit, which shows which branches and tags the commit is included in. Example: https://github.com/openshift/okd/commit/e278fba2d8a5aea6b7bd2636dce548f8d3463e11 https://github.com/openshift/okd/commit/e278fba2d8a5aea6b7bd...
  - pronik 5y ago
    Which is extremely easy: you click on the actual patch that has been merged and look under the commit message where all the tags containing this particular commit are shown.
    - arve0 5y ago
      Thank you. Tried on the commit in PR, did not show up, but the merge commit did. I guess it's dependent on merge strategy, where squash merge will not include the initial commit hash. Or maybe "pr commit view" excludes the same info.
- momothereal 5y ago
  - You can configure the auto-generated changelog to exclude users (e.g. dependabot) and labels[1] - The automated changelog is based on PR titles, which allows you to edit them without rewriting history, and labelling them for filtering/grouping. [1] https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configuration https://docs.github.com/en/repositories/releasing-projects-o...
  - krono 5y ago
    Those details should definitely have been a part of the blog post!
ddevault 5y ago
Automation like this is definitely a helpful first step for maintainers who want to prepare good release notes. 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: https://drewdevault.com/2021/05/19/How-to-write-release-notes.html https://drewdevault.com/2021/05/19/How-to-write-release-note... 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. Disclaimer: I represent a platform which competes with GitHub
oever 5y ago
"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." I thought GitHub was a closed-source SAAS by Microsoft.
- gnur 5y ago
  It is, but you cannot deny they host a majority of the open source projects that almost everyone uses daily.
OJFord 5y ago
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.)
dane-pgp 5y ago
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: https://github.com/kpcyrd/pacman-bintrans https://github.com/kpcyrd/pacman-bintrans
- mylesborins 5y ago
  this is definitely on our radar! We didn't do any major work on artifacts / assets as part of this effort but there are a bunch of backlogged items, including individual hashes, that we would like to do in the future.
  - jacques_chester 5y ago
    I'm interested in talking about this. Could you email me at my work address (in my profile)?
    - mylesborins 5y ago
      Might make the most sense to kick off a thread in https://github.com/github/feedback/discussions/5962 https://github.com/github/feedback/discussions/5962 so we can have a broader conversation
Vinnl 5y ago
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). For example, take a look at ESLint's autogenerated changelog [1]: 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) 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 https://github.com/eslint/eslint/blob/master/CHANGELOG.md
- madeofpalk 5y ago
  I agree - all commits to release notes doesn't seem very helpful. 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.
- steerablesafe 5y ago
  It feels like a missed opportunity of more automation, TBH. Notice that each commit mentions one or more bugs, probably enforced by commit hooks. 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"
mrzool 5y ago
As long as they don't break RSS feed support for releases... I use that feature heavily.
brainbag 5y ago
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. 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.
- mylesborins 5y ago
  You can use a `.github/release.yml` to organize sections based on labels. https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configuration https://docs.github.com/en/repositories/releasing-projects-o... I talked with one of the maintainers of conventional commits and we discussed writing an action to auto-label PRs based on conventional commits as a way to make a bridge between the two ways of working.
trinovantes 5y ago
> 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. I can't seem to find the documentation about integrating this with Actions But I am excited to finally be able to stop maintaining my custom auto-release-changelogs action https://github.com/Trinovantes/action-automatic-release https://github.com/Trinovantes/action-automatic-release
- mylesborins 5y ago
  Here's an example workflow that automates publishing to npm and creating a release with generated notes on the push of a tag https://github.com/MylesBorins/node-osc/blob/main/.github/workflows/create-release.yml https://github.com/MylesBorins/node-osc/blob/main/.github/wo...
mylesborins 5y ago
Hey all, I'm the PM for this launch feel free to ask any questions We are also collecting feedback in this discussion https://github.com/github/feedback/discussions/5962 https://github.com/github/feedback/discussions/5962
- rogerbinns 5y ago
  My many year peeve is github adding "Source code (zip)" to the files in a release. It is the repository state at the tag, and needs some processing (think similar to generating configure etc), hence being a hindrance for someone looking for the source code to use. I do provide a useful source code file, but can't override github being unhelpful.
- thuringia 5y ago
  Do you plan on creating „real“ Github Actions actions to integrate with releases? All examples mentioned here use the github-script action, which, to me, feels like a workaround. Or some form of direct integration into Github Actions, e.g. configure a workflow as „pre-release“ and the tags and release notes are created automatically? Given the currently documented automation features, I don’t see how this provides a tangible improvement to our team setups compared to current solutions like auto or semantic-release.
codyswann 5y ago
Would really be nice if it could attach all the issues that the release closed.
rtsao 5y ago
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. 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. 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). 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.

125 points by mrzool 5y ago

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. Maven plugin, if you're interested [1] https://github.com/heuermh/github-changes-maven-plugin https://github.com/heuermh/github-changes-maven-plugin

krono 5y ago

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.

arve0 5y ago
…which is nice, when the master is not tagged and you’re trying to find out “does this release include the bug fix in pr #123” (without cloning and/or jumping between tags/branches).
- krono 5y ago
  There's already a "compare" selector on the current/old releases page that lets you do just that with two clicks.
  - arve0 5y ago
    Thank you, that is useful, but basically same as "jumping" between branches. @pronik's reply was spot on, viewing the merge commit, which shows which branches and tags the commit is included in. Example: https://github.com/openshift/okd/commit/e278fba2d8a5aea6b7bd2636dce548f8d3463e11 https://github.com/openshift/okd/commit/e278fba2d8a5aea6b7bd...
- pronik 5y ago
  Which is extremely easy: you click on the actual patch that has been merged and look under the commit message where all the tags containing this particular commit are shown.
  - arve0 5y ago
    Thank you. Tried on the commit in PR, did not show up, but the merge commit did. I guess it's dependent on merge strategy, where squash merge will not include the initial commit hash. Or maybe "pr commit view" excludes the same info.
momothereal 5y ago
- You can configure the auto-generated changelog to exclude users (e.g. dependabot) and labels[1] - The automated changelog is based on PR titles, which allows you to edit them without rewriting history, and labelling them for filtering/grouping. [1] https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configuration https://docs.github.com/en/repositories/releasing-projects-o...
- krono 5y ago
  Those details should definitely have been a part of the blog post!

ddevault 5y ago

Automation like this is definitely a helpful first step for maintainers who want to prepare good release notes. 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: https://drewdevault.com/2021/05/19/How-to-write-release-notes.html https://drewdevault.com/2021/05/19/How-to-write-release-note... 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. Disclaimer: I represent a platform which competes with GitHub

oever 5y ago

"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." I thought GitHub was a closed-source SAAS by Microsoft.

gnur 5y ago
It is, but you cannot deny they host a majority of the open source projects that almost everyone uses daily.

OJFord 5y ago

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

dane-pgp 5y ago

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: https://github.com/kpcyrd/pacman-bintrans https://github.com/kpcyrd/pacman-bintrans

mylesborins 5y ago
this is definitely on our radar! We didn't do any major work on artifacts / assets as part of this effort but there are a bunch of backlogged items, including individual hashes, that we would like to do in the future.
- jacques_chester 5y ago
  I'm interested in talking about this. Could you email me at my work address (in my profile)?
  - mylesborins 5y ago
    Might make the most sense to kick off a thread in https://github.com/github/feedback/discussions/5962 https://github.com/github/feedback/discussions/5962 so we can have a broader conversation

Vinnl 5y ago

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). For example, take a look at ESLint's autogenerated changelog [1]: 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) 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 https://github.com/eslint/eslint/blob/master/CHANGELOG.md

madeofpalk 5y ago
I agree - all commits to release notes doesn't seem very helpful. 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.
steerablesafe 5y ago
It feels like a missed opportunity of more automation, TBH. Notice that each commit mentions one or more bugs, probably enforced by commit hooks. 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"

mrzool 5y ago

As long as they don't break RSS feed support for releases... I use that feature heavily.

brainbag 5y ago

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

mylesborins 5y ago
You can use a `.github/release.yml` to organize sections based on labels. https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configuration https://docs.github.com/en/repositories/releasing-projects-o... I talked with one of the maintainers of conventional commits and we discussed writing an action to auto-label PRs based on conventional commits as a way to make a bridge between the two ways of working.

trinovantes 5y ago

> 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. I can't seem to find the documentation about integrating this with Actions But I am excited to finally be able to stop maintaining my custom auto-release-changelogs action https://github.com/Trinovantes/action-automatic-release https://github.com/Trinovantes/action-automatic-release

mylesborins 5y ago
Here's an example workflow that automates publishing to npm and creating a release with generated notes on the push of a tag https://github.com/MylesBorins/node-osc/blob/main/.github/workflows/create-release.yml https://github.com/MylesBorins/node-osc/blob/main/.github/wo...

mylesborins 5y ago

Hey all, I'm the PM for this launch feel free to ask any questions We are also collecting feedback in this discussion https://github.com/github/feedback/discussions/5962 https://github.com/github/feedback/discussions/5962

rogerbinns 5y ago
My many year peeve is github adding "Source code (zip)" to the files in a release. It is the repository state at the tag, and needs some processing (think similar to generating configure etc), hence being a hindrance for someone looking for the source code to use. I do provide a useful source code file, but can't override github being unhelpful.
thuringia 5y ago
Do you plan on creating „real“ Github Actions actions to integrate with releases? All examples mentioned here use the github-script action, which, to me, feels like a workaround. Or some form of direct integration into Github Actions, e.g. configure a workflow as „pre-release“ and the tags and release notes are created automatically? Given the currently documented automation features, I don’t see how this provides a tangible improvement to our team setups compared to current solutions like auto or semantic-release.

codyswann 5y ago

Would really be nice if it could attach all the issues that the release closed.

rtsao 5y ago

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