Skip to content

Nx plugin to automate semantic versioning and CHANGELOG generation.

License

Notifications You must be signed in to change notification settings

lemonade-hq/semver

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

@jscutlery/semver NPM package @jscutlery/semver coverage status

@jscutlery/semver

Nx plugin for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.

Setup

Install

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.

Independent mode (default)

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.

Synced mode

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.

Usage

Release

Independent mode

Release project independently by running:

nx run my-project:version [...options]

You can leverage the built-in affected command to only version changed packages:

nx affected --target version [...options]

Synced mode

Release multiple projects at once:

nx run workspace:version [....options]

When run, this executor does the following

  1. Retrieve the current version of affected projects.
  2. Bump versions based on your commits.
  3. Generates CHANGELOGs based on your commits (uses conventional-changelog-angular under the hood).
  4. Creates a new commit including your package.json files and updated CHANGELOGs.
  5. Creates new tags with the new versions number.
  6. Push the releases (if enabled).
  7. Run post-targets.

Available options

name type default description
--dryRun boolean false run with dry mode
--noVerify boolean false skip git hooks
--push boolean false push the release against git origin
--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
--preid string undefined prerelease identifier
--versionTagPrefix string undefined specify the tag prefix
--postTargets string[] [] specify a list of target to execute post-release
--trackDeps boolean false use dependencies when calculating a version bump
--commitMessageFormat string undefined format the auto-generated message commit

Configuration using the file

Note that you can define the options you want to customize using the workspace.json file, eg:

{
  "executor": "@jscutlery/semver:version",
  "options": {
    "baseBranch": "master",
    "versionTagPrefix": "${target}@"
  }
}

Specify the level of change

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

Tag prefix customization

The --versionTagPrefix option allows you to customize the tag prefix.

With the sync mode the tag prefix is set to "v" by default, which is resolved to v0.0.1 for example. Note that only one tag is created for the whole workspace.

With independent mode the tag prefix uses the context target value, the default value is "${target}-" which is resolved to my-project-0.0.1 for example. Note that each project in the workspace is versioned with its own tag.

Commit message customization

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}

The version variable is resolved to the current release version, for instance 1.0.1. This option also allows you to interpolate the projectName variable:

release: bump ${projectName} to ${version} [skip ci]

Note that it's the right place to add common keywords to skip CI workflows, for example: [skip ci] for GitHub.

Triggering executors post-release

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"
      }
    }
  }
}

Note that options using the interpolation notation ${variable} are resolved with their corresponding value.

Resolved options

  • project
  • version
  • tag
  • tagPrefix
  • noVerify
  • dryRun
  • remote
  • baseBranch
  • notes

Built-in post-targets

Tracking dependencies

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:

  1. Enable versioning for each project in the dependency graph
  2. Set the trackDeps option to true on each of the projects
  3. Make sure that version is run on projects in the right order by configuring version's target dependencies in nx.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.

CI/CD usage

GitHub Actions

Here is an example running semver in a GitHub workflow:

name: default

on:
  push:
    branches:
      - 'master'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: git config
        run: |
          git config user.name "${GITHUB_ACTOR}"
          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
      - run: yarn install --frozen-lockfile
      - run: yarn nx version my-project --push --baseBranch master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You can found the complete example here.

Changelog

For new features or breaking changes see the changelog.

Contributors

This project follows the all-contributors specification.


Younes Jaaidi

πŸ› πŸ’» πŸ“– πŸ’‘ πŸ€”

Edouard Bozon

πŸ› πŸ’» πŸ“– πŸ’‘ πŸ€”

Gleb Mikheev

πŸ€”

Richard Lea

πŸ’»

Katona

πŸ› πŸ’»

ntziolis

πŸ›

RicardoJBarrios

πŸ’» πŸ€”

Sylvain Arnouts

πŸ›

GethsLeader

πŸ’» πŸ€”

Shahar Kazaz

πŸ’»

MiloΕ‘ Lajtman

πŸ› πŸ’»

Charley Bodkin

πŸ›

Jeffrey Bosch

πŸ’»

RaviTejaVattem

πŸ’»

Abishek PY

πŸ’» πŸ“–

Stefan Schneider

πŸ’»

Travis Jones

πŸ’» πŸ“– πŸ€”

Hichri Hassen

πŸ›

Gareth John

πŸ’»

Diego Juliao

πŸ› πŸ’» πŸ€”

Charlie Francis

πŸ›

Pierre Huyghe

πŸ’»

William Sedlacek

πŸ’» πŸ€”

Tycho Bokdam

πŸ€”

nicolashzmor

πŸ›

License

This project is MIT licensed.

About

Nx plugin to automate semantic versioning and CHANGELOG generation.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 99.2%
  • Other 0.8%