Automating Software Releases with Semantic Release

Introduction

Software teams aim to ship quality code frequently. However, managing releases manually is tedious and error-prone. Semantic release streamlines releasing by automating the whole process.

TL;DR:

• Semantic release automates the software release workflow by analyzing commit messages.
• It takes care of incrementing version numbers, generating changelogs, and publishing packages.
• To use it, projects must craft commit messages following the Conventional Commits standard.
• Overall, semantic release enables teams to deliver value faster by eliminating manual toil in releases.

What is Semantic Release?

Semantic release is a tool for automating software releases and version management. It facilitates implementing semantic versioning by analyzing commit messages to determine the next semantic version bump.

Here’s how it works:

• Developers author commit messages following the Conventional Commits specification.
• Semantic release analyzes commits and generates release notes.
• If a release is necessary, it publishes the package and creates a Git tag, and releases it on GitHub.

In short, the semantic release takes the human element out of software releases.

Benefits of Semantic Release

Automating releases with semantic release offers several advantages:

Easy Versioning

Semantic release handles version numbering automatically based on commits. Developers don’t have to decide manually whether a change warrants a major, minor, or patch release.

Consistent Releases

The process for publishing releases is codified and applied consistently across projects.

Improved Collaboration

Because semantic release relies on properly formatted commit messages, it encourages developers to collaborate better on commit hygiene.

Reduced Human Error

Taking humans out of the loop decreases the chances of mistakes in changelogs or accidentally introducing breaking changes.

Release Velocity

Automation enables releasing software faster and more frequently.

How to Use Semantic Release

Using semantic release involves adding it to your project and configuring a few key components.

Installation

Install the semantic release module:

npm install —save-dev semantic-release

Release Configuration

semantic-release is configured in release.config.js:

const config = {
	branches: ['main'],
	plugins: [
		'@semantic-release/commit-analyzer',
		'@semantic-release/release-notes-generator',
		'@semantic-release/github'
	]
}

module.exports = config

This configures the:

• Branch to release from
• Commit analyzer plugin
• Release notes generator
• GitHub plugin for releases

Commit Message Format

The commit analyzer plugin reads commit messages to determine the next semantic version. Messages must follow the Conventional Commits format:

<type>(<scope>): <description>

For example:

fix(parser): correct issue parsing numbers

Common types are:

• fix - for bug fixes
• feat - for new features
• docs - for documentation changes
• refactor - for code refactoring

Continuous Integration

Finally, the semantic release is typically run in CI to automate publishing releases for each commit. Here is an example .github/workflows/release.yml to trigger semantic release on GitHub Actions:

name: Release
on:
  workflow_dispatch:

jobs:
  release:
    permissions:
      contents: write
      pull-requests: write
      issues: write

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Release
        run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This runs semantic-release whenever a new workflow is triggered manually on GitHub. I personally find that more robust to have full control over when should a release job run.

Frequently Asked Questions

What commit message types can you use?

The common types are fix, feat, docs, style, refactor, and test. But semantic release supports any custom type.

Does semantic release work with git-flow?

Yes, semantic release works fine with git-flow style branching workflows.

How do you configure releasing from multiple branches?

You can specify multiple branch names in the “branches” array in release.config.js.

What CI tools can run semantic release?

Semantic-release works with CircleCI, Travis CI, GitHub Actions, and more. It runs on any CI tool that can install node modules.

Can I preview the next version before releasing it?

Yes, the semantic release includes a “dryRun” mode that simulates a release without publishing.

Summary

The semantic release allows teams to focus their efforts on building software rather than coordinating releases. By codifying releases and leveraging commit hygiene, it brings order and automation to the delivery process. This helps ship quality software faster and more reliably.