@sanity/semantic-release-preset

@sanity/semantic-release-preset

Features

• Uses Conventional Commits to generate release notes, changelogs and determine the version for new releases.
• Creates or updates a CHANGELOG.md file.
• Publishes to npm.
• Creates a new release on GitHub
• Updates GitHub issues and PRs that are resolved by a new release.
• Commits and pushes the current version to package.json.
• Keep the year in LICENSE up to date.

Table of contents

• Usage
  • Setup the release config
    • Optional: Configure prerelease branches
  • Minimal GitHub Release workflow
    • If you're unable to make it work chances are your issue is documented in the semantic-release troubleshooting docs
  • Opinionated GitHub Release workflow
    • TODO more docs are coming, we're actively exploring the optimal setup
• Next steps, for even more automation

Usage

npm i -D @sanity/semantic-release-preset

If your package manager don't auto install peer dependencies make sure to install semantic-release:

npm i -D semantic-release

Setup the release config

Create a .releaserc.json:

{
  "extends": "@sanity/semantic-release-preset",
  "branches": ["main"]
}

The branches array is mandatory, and in most repositories you should put the default git branch here (main, or master if it's an older repository).

Optional: Configure prerelease branches

If you have stable releases going out from the git branch main, and want commits on the branch beta to result in only being installable with the npm dist-tag beta:

npm i package-name@beta

But not on:

npm i package-name # or npm i package-name@latest

Then use this config:

{
  "extends": "@sanity/semantic-release-preset",
  "branches": ["main", { "name": "beta", "prerelease": true }]
}

Minimal GitHub Release workflow

This is the bare minimum required steps to trigger a new release. This will push a new release every time an eliglible commit is pushed to git. Check the opinionated flow to see how to trigger releases manually. Create .github/workflows/ci.yml:

---
name: CI

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          # Need to fetch entire commit history to
          # analyze every commit since last release
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          cache: npm
          node-version: lts/*
      - run: npm ci
      - run: npm test --if-present
      # Branches that will release new versions are defined in .releaserc.json
      # @TODO uncomment after verifying with --dry-run we're ready to go
      # - run: npx semantic-release
      - run: npx semantic-release --dry-run
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

It's important that you use --dry-run in the npx semantic-release command until you've verified that semantic-release is setup correctly and is able to detect your release branches and published version numbers. If you don't you may accidentally release a wrong version on npm, know that you can't simply unpublish accidents so it's best to be safe.

You need two secrets, secrets.GITHUB_TOKEN is always provided to GitHub actions, but if you try to --dry-run locally you'll need to create a token. It's easiest to just push commits and inspect the workflow output. You can add --debug to the npx semantic-release command to see more verbose logs if there's a tricky error.

The secrets.NPM_PUBLISH_TOKEN is provided on our GitHub org. If you're outside it you'll need to create it with auth-only 2FA and add it to the repository secrets.

If you're unable to make it work chances are your issue is documented in the semantic-release troubleshooting docs

Once you've confirmed with --dry-run that everything is looking good and semantic-release will perform the actions you expect it to, go ahead and edit .github/workflows/release.yml:

---
name: CI

on:
  # Build on pushes branches that have a PR (including drafts)
  pull_request:
  # Build on commits pushed to branches without a PR if it's in the allowlist
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          # Need to fetch entire commit history to
          # analyze every commit since last release
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          cache: npm
          node-version: lts/*
      - run: npm ci
      - run: npm test --if-present
      # Branches that will release new versions are defined in .releaserc.json
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}

If this is on a brand new package that haven't published to npm yet, make a commit like this:

git add .github/workflows/release.yml
git commit -m "feat: initial release"
git push

If you're onboarding a package that already has a published version history:

git add .github/workflows/release.yml
git commit -m "fix: use semantic-release"
git push

Check the Release Workflow docs for more information.

Opinionated GitHub Release workflow

1. This flow runs a build task for linting and things that only need to run once.
2. Runs test, which runs a matrix of operating systems and Node.js versions.
3. FInally, runs release, if the workflow started from a workflow_dispatch, it is skipped on push.

TODO more docs are coming, we're actively exploring the optimal setup

Next steps, for even more automation

• Setup Renovatebot dependencies automation with our preset.