semantic-release

What is semantic-release?

The semantic-release npm package automates the versioning and package publishing process based on semantic versioning (SemVer) principles. It analyzes commits since the last release to determine the type of version change (major, minor, or patch) and generates a changelog. It then publishes the new version to npm and can also update GitHub/GitLab releases.

What are semantic-release's main functionalities?

Automated Version Management

Automatically analyzes commits, determines the next semantic version, generates a changelog, and publishes the package. The code snippet shows a basic configuration in a package.json file.

"release": {
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Customizable Plugins

semantic-release's behavior can be customized with plugins. This example configures the commit analyzer and release notes generator to use the Angular preset.

"plugins": [
  ["@semantic-release/commit-analyzer", {
    "preset": "angular"
  }],
  ["@semantic-release/release-notes-generator", {
    "preset": "angular"
  }],
  "@semantic-release/npm",
  "@semantic-release/github"
]

Continuous Integration (CI) Configuration

Integrates with CI tools like GitHub Actions to automate the release process. This example shows a GitHub Actions workflow that sets up a job for semantic-release.

{
  "name": "semantic-release",
  "on": {
    "push": {
      "branches": ["main"]
    }
  },
  "jobs": {
    "release": {
      "runs-on": "ubuntu-latest",
      "steps": [
        {
          "name": "Checkout repository",
          "uses": "actions/checkout@v2"
        },
        {
          "name": "Setup Node.js",
          "uses": "actions/setup-node@v1",
          "with": {
            "node-version": "12"
          }
        },
        {
          "name": "semantic-release",
          "uses": "semantic-release-plus/docker@v1",
          "env": {
            "GITHUB_TOKEN": "${{ secrets.GITHUB_TOKEN }}",
            "NPM_TOKEN": "${{ secrets.NPM_TOKEN }}"
          }
        }
      ]
    }
  }
}

Other packages similar to semantic-release

standard-version

Similar to semantic-release, standard-version automates versioning and CHANGELOG generation based on commit messages, following the Conventional Commits specification. Unlike semantic-release, it does not automatically publish to npm or create GitHub/GitLab releases, focusing instead on versioning and changelog generation.

release-it

release-it is a CLI tool for automating versioning and package publishing, similar to semantic-release. It supports plugins for extending functionality but requires more manual configuration for things like generating changelogs and determining version bumps based on commit messages.

lerna

While primarily a tool for managing monorepos, Lerna also offers features for automated package publishing similar to semantic-release. It can increment package versions and publish to npm, but it's more focused on managing dependencies and versions across multiple packages in a monorepo.

README

semantic-release

npm i semantic-release

semantic-release provides "prepublish" and "postpublish" hooks so you automatically release the correct version.

Run semantic-release pre right before npm publish and semantic-release post right after.

For maximum comfort you can automate this inside your package.json:

"scripts": {
  "prepublish": "semantic-release pre",
  "postpublish": "semantic-release post"
}

Note: Even though semantic-release works around a limitation in npm's "prepublish" hook using it prints an error that you can safely ignore. See npm/npm#7118.

MIT License 2015 Stephan Bönnemann