Semi-Automatic npm and GitHub Releases with `gh-release` and `auto-changelog`

This is a blogpost I've been sitting on for over 1 yr because I haven't had the time to really study all the approaches and decide on the best one.

Kent C. Dodds is notable for setting up fully automated releases for all his OSS libraries. I think that is good for high volumes of releases, but it does involve extra setup steps that may not be worth it for smaller, more casual libraries.

I picked up this semi-automatic method from Bret Comnes at Netlify and I quite like it. Writing it down since I refer to it approximately once a month.

Steps

Given a library you want to automate releases of:

npm i -D auto-changelog gh-release

add npm scripts:

{
  "scripts": {
     "version": "auto-changelog -p --template keepachangelog && git add CHANGELOG.md",
     "prepublishOnly": "git push && git push --tags && gh-release"
  }
}

Now whenever you want to cut a new release:

• you run npm version (I have a shortcut for npm version patch) to bump the package version and generate the CHANGELOG.
• You have the time to inspect and modify the changelog, then you can npm publish to push this new release to GitHub as well as to npm.

Why

Using GitHub releases is a nice best practice for people watching your repo but also if you have any downloadable artifacts people can grab it right off your GitHub.

You retain manual control of your CHANGELOG and your publish process, while automating the boring parts of pushing releases and generating the base changelog. Also no extra npm tokens or infrastructure need be setup to do this, it's all done on your own machine.

More advice

I advise adding a prepublish script to run builds and tests as well - I have been caught a couple times publishing bad versions because I forgot these in some packages.

This is NOT the last word on how best to automate releases - this is just what works for me now, but I have a LONG list of other methods to investigate but not enough time to try them all out right now.

Related writing from me: Best Practice Open Source Repo Setup

Here's a list of release tech I have yet to try out but made notes of:

• https://snyk.io/blog/github-actions-to-securely-publish-npm-packages/
• https://github.com/semantic-release/semantic-release
• https://github.com/atlassian/changesets/
• https://github.com/release-drafter/release-drafter
• https://github.com/googleapis/release-please
• https://github.com/intuit/auto (Orta writeup here: https://artsy.github.io/blog/2019/01/03/label-based-prs/)
• https://github.com/algolia/shipjs
• https://www.npmjs.com/package/release-it
• lerna-changelog
• https://github.com/beyonk-adventures/svelte-mapbox/tree/master/.github/workflows
• https://github.com/infinitered/open-source/blob/master/Continuous-Deployment-Setup-NPM.md
• Github actions for nightly deploys by Orta https://github.com/microsoft/TypeScript-Website/issues/130#issuecomment-663471663-permalink
• more tips here: https://mobile.twitter.com/swyx/status/1118966159641067521
• linting: https://blog.codonomics.com/2020/03/3-musketeers-eslint-husky-lint-staged.html