/semantic-deployment-in-2024

An opinionated workflow for automating away some of the tedium of releasing versioned software.

Semantic Deployment, 2024 Edition

This is an opinionated workflow for automating away some of the tedium of releasing versioned software.

It combines SemVer, Conventional Commits, GitHub Actions, Release Please, and Semantic Pull Request.

The idea is to add a bit of semantic information to each pull request as your write them, then let automation take care of writing changelogs, determining version numbers, and publishing release artifacts to registries like GitHub and npm.

video

🍿 Watch the 5-minute demo video on YouTube

Why?

I maintain a lot of software packages. A lot of that maintenance is mindless work, so I always look for opportunities to automate away the mindless parts. When I worked on the Electron team at GitHub, we developed this semantic workflow to help manage the influx of community contributions to the project, and to remove the human subjectivity from the process of deciding how to version software.

The ideal workflow

The contribution process works like this:

  1. Contributors open pull requests, giving them titles with semantic prefixes like fix: and feat:.
  2. When you merge a pull request, it's automatically added to a long-running Release pull request that accumulates changes.
  3. When you're ready to cut a release, merge the Release pull request and a release is created automatically.

That's it! You never think about version numbers again.

Tools

This workflow combines the following ideologies, specifications, and tools:

  • Semantic Versioning (aka SemVer), a methodology for applying version numbers to software.
  • Conventional Commits, a specification for adding human and machine readable meaning to commit messages
  • GitHub Actions, a GitHub feature for automating your work.
  • Release Please, a tool that automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects.
  • Semantic Pull Request, a GitHub action that validates pull request titles have semantic prefixes.

Setting it up

🐢🚀 This guide caters to a Node.js crowd, but you can use this setup for dozens of languages

  1. Create a Release actions workflow that uses release-please. (Example).
  2. Create a Semantic Pull Request actions workflow that uses semantic-pull-request to lint your pull request titles. (Example)
  3. Create a GitHub Personal Access Token (PAT) with Repo and Workflow scopes.
  4. Add the GitHub PAT to your repo as a Repository Secret
  5. Create an npm token.
  6. Add the npm token to your repo as a Repository Secret.
  7. Configure your repo to allow Read and write permssions for Actions workflows in Settings > Actions > General
  8. Configure your repo to only allow squash merging, and set Pull request title as the default commit message.

Gotchas

  • Educating contributors may be the hardest part. Some users have never used semantic prefixes before, so they may surprised at first when they open a pull request and see a failing check. Fortunately you as a maintainer have the power to change the title of a PR on behalf of a user, to make it pass the semantic check.
  • You still gotta push a few buttons. The way release-please works is by accumulating changes in a Release PR. It's up to you to decide when to merge this PR and trigger a releas. This is arguably a feature and one of the fundamental ideas behind release-please, but it does mean you have to remember to go merge that Release PR to actually create a release.
  • Configure setup-node properly. Make sure you set registry-url for the setup-node action in your release workflow, or your package will fail to publish.