sanity-io@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
versiontopackage.json. - Keep the year in LICENSE up to date.
Table of contents
- Usage
- Next steps, for even more automation
Usage
npm i -D @sanity/semantic-release-presetIf your package manager don't auto install peer dependencies make sure to install semantic-release:
npm i -D semantic-releaseSetup 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@betaBut not on:
npm i package-name # or npm i package-name@latestThen 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 pushIf 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 pushCheck the Release Workflow docs for more information.
Opinionated GitHub Release workflow
- This flow runs a
buildtask for linting and things that only need to run once. - Runs
test, which runs a matrix of operating systems and Node.js versions. - FInally, runs
release, if the workflow started from aworkflow_dispatch, it is skipped onpush.
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.