Nx plugin for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.
Using Nx:
npm install -D @jscutlery/semver
nx g @jscutlery/semver:install
Using Angular CLI:
ng add @jscutlery/semver
This package allows you to manage your monorepo using one of two modes: Synced or Independent.
Allow multiple projects to be versioned independently. This way you release only what you want and consumers don't get updates they don't need. This allows small, rapid and incremental adoption of your packages.
Allow multiple projects to be versioned in a synced/locked mode. Use this if you want to automatically tie all package versions together. This mode is useful when you are working with only one product. One issue with this approach is that a major change in any project will result in all projects having a new major version.
Release project independently by running:
nx run my-project:version [...options]
You can leverage the affected command to only version changed packages:
nx affected --target version [...options]
Release workspace by running:
nx run workspace:version [...options]
- Retrieve the current version by looking at the last
git tag
. - Bump
package.json
version based on your commits. - Generates CHANGELOG based on your commits (uses conventional-changelog-angular under the hood).
- Creates a new commit including your
package.json
file and updated CHANGELOG. - Creates new tag with the new version number.
- Pushes the release (if enabled).
- Runs post-targets (if defined).
name | type | default | description |
---|---|---|---|
--dryRun |
boolean |
false |
run with dry mode |
--noVerify |
boolean |
false |
skip git hooks |
--push |
boolean |
false |
push the release to the remote repository |
--syncVersions |
boolean |
false |
lock/sync versions between projects |
--skipRootChangelog |
boolean |
false |
skip generating root changelog |
--skipProjectChangelog |
boolean |
false |
skip generating project changelog |
--origin |
string |
'origin' |
push against git remote repository |
--baseBranch |
string |
'main' |
push against git base branch |
--changelogHeader |
string |
undefined |
custom Markdown header for changelogs |
--releaseAs |
string |
undefined |
specify the level of change (details) |
--preid |
string |
undefined |
specify the prerelease identifier (eg: alpha, beta) (details) |
--tagPrefix |
string |
undefined |
specify the tag prefix (details) |
--postTargets |
string[] |
[] |
specify the list of target to execute post-release (details) |
--trackDeps |
boolean |
false |
bump dependent packages (bump A if A depends on B) (details) |
--allowEmptyRelease |
boolean |
false |
force a patch increment even if library source didn't change |
--commitMessageFormat |
string |
undefined |
format the auto-generated message commit (details) |
--preset |
string |
'angular' |
specify the commit message guideline preset |
You can customize the default configuration using the definition file (angular.json
, workspace.json
or project.json
):
{
"executor": "@jscutlery/semver:version",
"options": {
"baseBranch": "master",
"preset": "conventional",
"tagPrefix": "${projectName}@"
}
}
The --releaseAs
option allows you to release a project with a version that is incremented by a specified level.
Level can be one of major
, minor
, patch
, premajor
, preminor
, prepatch
, or prerelease
, for instance:
nx run workspace:version --releaseAs=major
nx run workspace:version --releaseAs=minor
nx run workspace:version --releaseAs=patch
nx run workspace:version --releaseAs=prerelease --preid=alpha
nx run workspace:version --releaseAs=prerelease --preid=beta
The --tagPrefix
option allows you to customize the tag prefix.
In sync mode only one tag is created for the whole workspace, the tag prefix is set to v
by default, which is resolved for instance to v0.0.1
.
In independent mode, the tag prefix uses the contextual project name, the default value is ${projectName}-
which is resolved for instance to my-project-0.0.1
. Note that each project in the workspace is versioned with its own tag.
The --commitMessageFormat
option allows you to customize the commit message. By default, the commit message is formatted as the following:
chore(${projectName}): release version ${version}
Contextual variables resolved by this option:
version
the current release version (for instance1.0.0
)projectName
the project name to be versioned (for instancemy-project
)
Note that it's the right place to add common keywords to skip CI workflows, for example: [skip ci]
for GitHub, eg:
release: bump ${projectName} to ${version} [skip ci]
The --postTargets
option allows you to run targets post-release. This is particularly handful for publishing packages on a registry or scheduling any other task.
Here is a configuration example using @jscutlery/semver:github
to create a GitHub Release and ngx-deploy-npm:deploy
to publish on NPM:
{
"targets": {
"version": {
"executor": "@jscutlery/semver:version",
"options": {
"postTargets": ["my-project:publish", "my-project:github"]
}
},
"github": {
"executor": "@jscutlery/semver:github",
"options": {
"tag": "${tag}",
"notes": "${notes}"
}
},
"publish": {
"executor": "ngx-deploy-npm:deploy",
"options": {
"access": "public"
}
}
}
}
Contextual variables resolved by this option:
projectName
versioned project nameversion
semver versiontag
formatted git tagnotes
release notes
@jscutlery/semver:github
GiHub Release Support@jscutlery/semver:gitlab
GitLab Release Support
The --trackDeps
option indicates that direct dependencies in the project's dependency graph should be taken into account when incrementing the
version. If no version-incrementing changes are present in the project, but are present in one or more dependencies, then the project will receive a patch
version increment.
If you wish to track changes at any depth of your dependency graph, then you should do the following:
- Enable versioning for each project in the dependency graph
- Set the
trackDeps
option totrue
on each of the projects - Make sure that
version
is run on projects in the right order by configuringversion
's target dependencies innx.json
:
{
"targetDependencies": {
"version": [
{
"target": "version",
"projects": "dependencies"
}
]
}
}
This setup will cause a cascade of version increments starting at the deepest changed dependency,
then continuing up the graph until the indicated project is reached.
Additionally, if used in conjunction with nx run-many --all
, or nx affected
,
then it will avoid attempting to version dependencies multiple times.
Here is an example running semver in a GitHub workflow:
name: release
on:
- workflow_dispatch
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: '16'
- name: Setup Git
run: |
git config user.name "GitHub Bot"
git config user.email "gituser@example.com"
- run: yarn install --frozen-lockfile
- name: Version
shell: bash
run: yarn nx affected --base=last-release --target=version
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Tag last-release
shell: bash
run: |
git tag -f last-release
git push origin last-release --force
Note that secrets.GITHUB_TOKEN
is automatically provided by the GitHub Actions, you don't need to set up anything.
Here is an example running semver in the GitLab CI:
stages:
- release
release:
rules:
- if: $CI_COMMIT_BRANCH == "master"
when: manual
stage: release
image: node:16.13.2
before_script:
- git config --global user.name "GitLab Bot"
- git config --global user.email "gituser@example.com"
- git remote set-url origin http://gitlab-ci-token:${DEPLOY_KEY}@gitlab.com/org/project.git
script:
- yarn install --frozen-lockfile
- yarn nx affected --target=version --base=last-release
- git tag -f last-release
- git push origin last-release --force -o ci.skip
Note that you might need to configure a deploy key in order to push to your remote repository.
For new features or breaking changes see the changelog.
This project follows the all-contributors specification.
This project is MIT licensed.