@netly/semantic-release-config
v1.0.3
Published
Sharable configuration for semantic-release, extends experience for publishing to NPM & Github: generates release-notes, changelog, publishes new version with Github actions.
Downloads
26
Maintainers
Readme
@netly/semantic-release-config for internal use
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
topackage.json
. - Keep the year in LICENSE up to date.
Table of contents
Usage
npm i -D @netly/semantic-release-config
There's a convention in semantic-release
presets to have it as a peer, which would make the install setup look like this:
npm install -D @netly/semantic-release-config
This leaves it to you to keep both dependencies up to date. This package is primarily designed to ease our own internal @netly
npm packages, and thus we prefer for it to be a single dependency.
That way we avoid mismatch bugs where bots might make a PR that updates semantic-release
to a new, breaking, major version. But fail to also update @netly/semantic-release-config
causing it to fail.
By declaring it as a normal dependency
we avoid these issues, and reduce churn and PR noise.
Setup the release config
Create a .releaserc.json
:
{
"extends": "@netly/semantic-release-config",
"branches": ["main", "master"]
}
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 v3
to result in only being installable with the npm dist-tag dev-preview
:
npm i package-name@dev-preview
But not on:
npm i package-name # or npm i package-name@latest
Then use this config:
{
"extends": "@netly/semantic-release-config",
"branches": [
"main",
{ "name": "v3", "channel": "dev-preview", "prerelease": true }
]
}
Optional: Advanced prerelease branches
On many studio v3 plugins we're using the main
git branch to push prereleases that are installable as:
npm i package-name@studio-v3
And that's saved to the package.json
as:
{
"dependencies": {
"package-name": "^1.0.0-v3-studio.1"
}
}
To run that setup use:
{
"extends": "@netly/semantic-release-config",
"branches": [
{ "name": "studio-v2", "channel": "latest" },
{ "name": "main", "channel": "studio-v3", "prerelease": "v3-studio" }
]
}
Why not use "prerelease": true
?
If prerelease
is true
instead of v3-studio
this is what happens when it's installed:
{
"dependencies": {
"package-name": "^1.0.0-studio-v3.1"
}
}
Since we use the name studio-v3
as the channel
, the prerelease increment makes it look like the studio version is v3.1
, which is confusing. Alternatively, you could set channel
to v3-studio
but then the install command would change to this:
npm i package-name@v3-studio
And since we always say "Studio v3" and never "v3 Studio" when talking about the new version it's better to use both channel
and prerelease
to set the optimal ordering individually.
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:
node-version: lts/*
cache: 'npm'
- run: npm ci --no-audit --prefer-offline
- run: npm test --if-present
- run: npm run lint --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:
node-version: lts/*
cache: 'npm'
- run: npm ci --no-audit
- run: npm test --if-present
- run: npm run lint --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.