@lomray/semantic-release-monorepo
v1.0.1
Published
Plugins for `semantic-release` allowing it to be used with a monorepo.
Downloads
31
Readme
semantic-release-monorepo
This is a fork of original repository with apply all PR from original repository.
Apply semantic-release
's automatic publishing to a monorepo.
Why
The default configuration of semantic-release
assumes a one-to-one relationship between a GitHub repository and an npm
package.
This library allows using semantic-release
with a single GitHub repository containing many npm
packages.
How
Instead of attributing all commits to a single package, commits are assigned to packages based on the files that a commit touched.
If a commit touched a file in or below a package's root, it will be considered for that package's next release. A single commit can belong to multiple packages and may trigger the release of multiple packages.
In order to avoid version collisions, generated git tags are namespaced using the given package's name: <package-name>-<version>
.
Install
Both semantic-release
and semantic-release-monorepo
must be accessible in each monorepo package.
npm install -D semantic-release semantic-release-monorepo
Usage
Run semantic-release
in an individual monorepo package and apply semantic-release-monorepo
via the extends
option.
On the command line:
$ npm run semantic-release -e semantic-release-monorepo
Or in the release config:
{
"extends": "semantic-release-monorepo"
}
NOTE: This library CAN'T be applied via the plugins
option.
{
"plugins": [
"semantic-release-monorepo" // This WON'T work
]
}
With Yarn Workspaces
$ yarn workspaces run semantic-release -e semantic-release-monorepo
With Lerna
The monorepo management tool lerna
can be used to run semantic-release-monorepo
across all packages in a monorepo with a single command:
lerna exec --concurrency 1 -- npx --no-install semantic-release -e semantic-release-monorepo
With pnpm
pnpm has built-in workspace functionality for monorepos. Similarly to the above, you can use pnpm to make release in all packages:
pnpm -r --workspace-concurrency=1 exec -- npx --no-install semantic-release -e semantic-release-monorepo
Thanks to how npx's package resolution works
, if the repository root is in $PATH
(typically true on CI), semantic-release
and semantic-release-monorepo
can be installed once in the repo root instead of in each individual package, likely saving both time and disk space.
Advanced
This library modifies the context
object passed to semantic-release
plugins in the following way to make them compatible with a monorepo.
| Step | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| analyzeCommits
| Filters context.commits
to only include the given monorepo package's commits. |
| generateNotes
| Filters context.commits
to only include the given monorepo package's commits.Modifies context.nextRelease.version
to use the monorepo git tag format. The wrapped (default) generateNotes
implementation uses this variable as the header for the release notes. Since all release notes end up in the same Github repository, using just the version as a header introduces ambiguity. |
tagFormat
Pre-configures the tagFormat
option to use the monorepo git tag format.
If you are using Lerna, you can customize the format using the following command:
"semantic-release": "lerna exec --concurrency 1 -- semantic-release -e semantic-release-monorepo --tag-format='${LERNA_PACKAGE_NAME}-v\\${version}'"
Where '${LERNA_PACKAGE_NAME}-v\\${version}'
is the string you want to customize. By default it will be <PACKAGE_NAME>-v<VERSION>
(e.g. foobar-v1.2.3
).