release-with-changelog: A superior GitHub action to manage your releases

What the hell are you talking about?

There are these core actions maintained by GitHub, under the @actions/... scope, that houses actions which automate common tedious tasks like posting output of a build, creating releases, publishing your npm modules etc.

But these actions are not that powerful per se, they only provide the most generic ways for going about with performing an action.

For example, if you wanted to automate creating a release on pushing some tags, which also contains a body of changelog commits, you can not, you are stuck with the default static input that @actions/create-release provides. This was a real requirement for us. You have to build on top of it.

Out of this necessity was born release-with-changelog, a GitHub action to automate your releases without having to worry about manually generating changelogs for every release you make.

This action takes a list of commits between the current tag and the last available tag, and uses that as body when creating releases, it's as simple as that. Not quite though, there are a little details I ignored to mention here as they require their own in depth explanation. If you want to dig more into the details, there's no other place than the self explaining code to look at 😉.

How do I use this?

You can find a sample workflow snippet in the readme or look at how some other (famous 👏) repository use this action in production here.

jobs:
  Release:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
    - uses: notlmn/release-with-changelog@v2
      with:
        header: '### Changelog'
        footer: 'Custom footer'
        include-hash: true
        include-range: true
        token: ${{ secrets.GITHUB_TOKEN }}

It's as simple as that!

You can find what these options are and what they do in a bit more detail here.

The documentation is a bit rough on the edges, so beware, but please go ahead and see if this helps you in your open-source projects.

I see, is anyone using this already?

Yes! See how some existing open-source projects are using this extension:

• Refined GitHub: A browser extension with more than 12k stars uses this extension to automate its releases, and helps its users notified on new features.
• browser-extension-template: A GitHub template to help you get started with building your first browser extension, also including this action to automate releases.

Shameless plug: Read how I ended up creating the later project in my previous post.

Credits where it is due

Kudos to the awesome @fregante for helping me out crushing bugs and adding features to the action. ❤

Help us improve it

We're currently working on adding features like template for changelog, excluding commits from changelog, and more.

Do you like it? Do you hate it? Please feel free to let us know the same in comments or opening issues on the repository. If you have any ideas, reach out to me using comments, twitter, or any other creative way you could think of. I promise I won't bite.

Comments

[Almenon]

Neat. It would be cool if it could write to a changelog file as well. For example for github.com/Almenon/AREPL-vscode I have a CHANGELOG.md file that I keep up to date. The changelog shows up in VSCode if you look at the extension.

What's the benefit/drawbacks/differences of using this over github.com/semantic-release/semant...?

[Laxman]

Well it's not intended to replicate what semantic-release does, it's intended to do one thing only for specific audience, take two tags, generate diff, use that for creating a release. And not touching the parts of repo.

About changelog file, there's r0mflip/ghtags that you can look at.

Hope that helps!