How it Works

Before we talk about implementation, it’s important to understand what work our tools will perform. That way, if there are problems or modifications, we can fix them. semantic-release is going to do the majority of the work here — they say it best on their README.

It automates the whole package release workflow including determining the next version number, generating the release notes and publishing the package.

The next version number

Upon release, to determine the next version number, the tool reads commits since the previous release, which it locates by looking at your Git tags. Based on the type of commit, it can determine how to bump up the version of the package. For this to work, commits need to be written in a certain way.

By default, semantic-release uses the Angular Commit Message Conventions. This is critical because consumers of the package need to know if a new version releases a new feature, introduces breaking changes or both. For example, if someone commits fix(pencil): stop graphite breaking when too much pressure applied , semantic-release knows that this contains a fix and that it has to create a patch release. This will increase the version in the minor version range (0.0.x).

Never seen this type of versioning before? Check out Semantic Versioning.

After analyzing all the commits, it takes the highest priority type of change and makes sure that’s the one that is applied. For example, if two commits were introduced since the last release, one breaking (x.0.0) and one minor (0.0.x), it would know to just up the version by breaking range.

Generating release notes

Once it’s found out what type of release the next version is, changelog notes are generated based on the commits. semantic-release doesn’t use the conventional CHANGELOG.md file to notify users of what’s changed, it does so with a Github Release which is attached to a Git tag.

Here’s an example of a Github Release that semantic-release generates and pushes on builds.

Automating with Github actions

semantic-release is the tool that performs most of the work, but we still need a service to run the tool on. That’s where Github Actions comes into play. When pull-requests are merged into master (or any base branch you configure), Github Actions will run a job that simply runs semantic-release with your configuration. All the work we described previously will be performed.

Here’s an example of a Github Actions run using semantic-release to publish a new release.