Ninja Pumpkin Mutants

    @jscutlery/semver
    TypeScript icon, indicating that this package has built-in type declarations

    2.29.0 • Public • Published
    @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 affected command to only version changed packages:

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

    Synced mode

    Release workspace by running:

    nx run workspace:version [...options]
    

    When run, this executor does the following

    1. Retrieve the current version by looking at the last git tag.
    2. Bump package.json version based on the commits.
    3. Generates CHANGELOG based on the commits (uses conventional-changelog-angular under the hood).
    4. Creates a new commit including the package.json file and updated CHANGELOG.
    5. Creates a new tag with the new version number.
    6. Pushes the version to the remote repository.
    7. Runs post-targets hook to publish the version on NPM, GitHub or GitLab.

    Important: merge commits messages are ignored by the tool when calculating next version to bump.

    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 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
    --skipCommitTypes string[] [] treat commits with specified types as non invoking version bump (details)
    --skipCommit boolean false skips generating a new commit, leaves all changes in index, tag would be put on last commit (details)
    --commitMessageFormat string undefined format the auto-generated message commit (details)
    --preset string | object 'angular' customize Conventional Changelog options (details)

    Overwrite default configuration

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

    Customizing Conventional Changelog options

    Any of the command line parameters accepted by Conventional Changelog can be provided via the prefix option. Please refer to the conventional-changelog-config-spec for details on available configuration options.

    Customizing CHANGELOG Generation

    As an example, suppose you're using GitLab, rather than GitHub, you might modify the following variables:

    {
      "executor": "@jscutlery/semver:version",
      "options": {
        "preset": {
          "commitUrlFormat": "{{host}}/{{owner}}/{{repository}}/commit/{{hash}}",
          "compareUrlFormat": "{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}"
          "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}"
        }
      }
    }
    

    Version calculation

    This package is tag-based, which means it never reads the package.json to retrieve the current version. Instead, it looks for a tag matching the --tagPrefix (i.e demo-x.y.z). Then, if no tag is found it fallbacks to 0.0.0, and calculates the initial version based on all changes since the first commit. In the other case, if there are matching tags, it retrieves the last one and calculates the new version from it.

    To detect a new version this package looks into the commit history and checks if any source files changed since the last version.

    Note: Major zero version 0.x.y is for initial development. Anything may change at any time so the consumer won't get any new minor version using the caret or tilde compatibility range, for instance version 0.3.1 won't be resolved if the consumer wants ^0.2.0.

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

    Contextual variables resolved by this option:

    • version the current release version (for instance 1.0.0)
    • projectName the project name to be versioned (for instance my-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]
    

    Skipping release for specific types of commits

    To avoid releasing a new version if something non-influencing on release was changed(for example, documentation), you can provide skipCommitTypes option. In this case, any commit with a specified type would be ignored when calculating if there is a need to bump version. For example, if you had only one commit from the last version:

    docs(project): update documentation about new feature
    

    would not cause a new release (because --skipCommitTypes=docs,ci was specified).

    And two commits:

    docs(project): update documentation about new feature
    fix(project): get rig of annoying bug
    

    would produce a patch bump.

    Please keep in mind that changelog would be generated by conventional-changelog which ignores some types by design (i.e. docs, test and others).

    Skipping commit

    In some cases, your release process relies only on tags and you don't want a new commit with version bumps and changelog updates to be made. To achieve this, you can provide the --skipCommit flag and changes made by the library would stay in the index without committing. The tag for the new version would be put on the last existing commit.

    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:npm", "my-project:github"]
          }
        },
        "github": {
          "executor": "@jscutlery/semver:github",
          "options": {
            "tag": "${tag}",
            "notes": "${notes}"
          }
        },
        "npm": {
          "executor": "ngx-deploy-npm:deploy",
          "options": {
            "access": "public"
          }
        }
      }
    }
    

    Contextual variables resolved by this option:

    • projectName versioned project name
    • version semver version
    • tag formatted git tag
    • notes release 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: 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.

    GitLab CI

    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.

    Changelog

    For new features or breaking changes see the changelog.

    Contributors

    This project follows the all-contributors specification.

    Younes Jaaidi
    Younes Jaaidi

    🐛 💻 📖 💡 🤔
    Edouard Bozon
    Edouard Bozon

    🐛 💻 📖 💡 🤔
    Gleb Mikheev
    Gleb Mikheev

    🤔
    Richard Lea
    Richard Lea

    💻
    Katona
    Katona

    🐛 💻
    ntziolis
    ntziolis

    🐛
    RicardoJBarrios
    RicardoJBarrios

    💻 🤔
    Sylvain Arnouts
    Sylvain Arnouts

    🐛
    GethsLeader
    GethsLeader

    💻 🤔
    Shahar Kazaz
    Shahar Kazaz

    💻
    Miloš Lajtman
    Miloš Lajtman

    🐛 💻
    Charley Bodkin
    Charley Bodkin

    🐛
    Jeffrey Bosch
    Jeffrey Bosch

    💻
    RaviTejaVattem
    RaviTejaVattem

    💻
    Abishek PY
    Abishek PY

    💻 📖
    Stefan Schneider
    Stefan Schneider

    💻
    Travis Jones
    Travis Jones

    💻 📖 🤔
    Hichri Hassen
    Hichri Hassen

    🐛
    Gareth John
    Gareth John

    💻
    Diego Juliao
    Diego Juliao

    🐛 💻 🤔
    Charlie Francis
    Charlie Francis

    🐛
    Pierre Huyghe
    Pierre Huyghe

    💻
    William Sedlacek
    William Sedlacek

    💻 🤔
    Tycho Bokdam
    Tycho Bokdam

    🤔
    nicolashzmor
    nicolashzmor

    🐛
    Raúl Julián López Caña
    Raúl Julián López Caña

    🐛 💻
    Miguel Suarez
    Miguel Suarez

    💻
    Katya Pavlenko
    Katya Pavlenko

    🐛 💻 🤔
    Hoon Oh
    Hoon Oh

    💻 🤔
    Kurt Hoyt
    Kurt Hoyt

    🐛
    Riain Condon
    Riain Condon

    💻 📖 💡
    lukelukes
    lukelukes

    🐛
    Ian Luca
    Ian Luca

    💻 🤔
    Matthias Stemmler
    Matthias Stemmler

    🐛
    Giora Guttsait
    Giora Guttsait

    🐛
    Derek Burgman
    Derek Burgman

    🐛 💻
    James
    James

    🐛 💻
    ndrsg
    ndrsg

    💻 🤔 🐛
    Fabian Schneider
    Fabian Schneider

    🐛 💻
    JD
    JD

    📖
    Daniel Beck
    Daniel Beck

    💻 📖
    Florian Guitton
    Florian Guitton

    💻

    License

    This project is MIT licensed.

    Keywords

    none

    Install

    npm i @jscutlery/semver

    DownloadsWeekly Downloads

    52,835

    Version

    2.29.0

    License

    MIT

    Unpacked Size

    184 kB

    Total Files

    120

    Last publish

    Collaborators

    • yjaaidi
    • koalaa