@futureverse/nx-semantic-release-sync v0.11.1

@futureverse/nx-semantic-release-sync

nx plugin for automated releases, powered by semantic-release

How it works

Under the hood, it uses project graph from nx to analyze commits for every configured project and filters out these commits that doesn't affect given project or it's dependencies.

Installation

Run:

npm install -D @futureverse/nx-semantic-release-sync

Usage

In order to release your projects, add this executor to your configuration file (ex. project.json) in the workspace level, for those who want multiple projects with the same version number, the configuration will looks like this:

{
  "semantic-release": {
    "executor": "@futureverse/nx-semantic-release-sync:semantic-release",
    "options": {
      "projects": [
        {
          "name": "app1",
          "outputPath": "dist/libs/app1",
          "importPath": "@futureverse/app1"
        },
        {
          "name": "app2",
          "outputPath": "dist/libs/app2",
          "importPath": "@futureverse/app2"
        }
      ],
      "github": true,
      "changelog": true,
      "npm": true,
      "changelogFile": "./CHANGELOG.md",
      "tagFormat": "apps-v${VERSION}"
    }
  }
}

If you want to manage the projects independently, the configuration will looks like this:

{
  "semantic-release-app1": {
    "executor": "@futureverse/nx-semantic-release-sync:semantic-release",
    "options": {
      "projects": [
        {
          "name": "app1",
          "outputPath": "dist/libs/app1",
          "importPath": "@futureverse/app1"
        }
      ],
      "github": true,
      "changelog": true,
      "npm": true,
      "changelogFile": "./CHANGELOG.md",
      "tagFormat": "apps-v${VERSION}"
    }
  },
  "semantic-release-app2": {
    "executor": "@futureverse/nx-semantic-release-sync:semantic-release",
    "options": {
      "projects": [
        {
          "name": "app2",
          "outputPath": "dist/libs/app2",
          "importPath": "@futureverse/app2"
        }
      ],
      "github": true,
      "changelog": true,
      "npm": true,
      "changelogFile": "./CHANGELOG.md",
      "tagFormat": "apps-v${VERSION}"
    }
  }
}

After running this, the executor will do the following:

• Filter commits retrieved by semantic-release in order to find only these that affects selected project or it's dependencies.
• Perform semantic-release using following plugins (in this order:)
  • @semantic-release/commit-analyzer
  • @semantic-release/release-notes-generator
  • @semantic-release/changelog
  • @semantic-release/npm
  • @semantic-release/git
  • @semantic-release/github
• The result will be a fully versioned project. If you are releasing it as npm package, the package will be built, version in package.json will be updated and package itself will be published.

Configuration

Options can be configured in 3 ways:

1. cli: Passing them on the cli command
2. config file: Including them in a global nxrelease config file in the root of your monorepo (see below)
3. project: Within the options section of the executor for each project (project.json)

Multiple configurations are fully supported, allowing for global configuration options in the config file and then project specific overrides in the project.json. Options merged in the following order of precedence:

cli flags > project > config file > defaults

Note: Object/Array type options are shallowly merged. For example, if gitAssets is set in both the config file and the project options, the whole of the project options version will be used and the config file option will be discarded.

Configuration file

nx-semantic-release's options can be set globally via either:

• a nxrelease key in the project's package.json file
• a .nxreleaserc file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js
• a nxrelease.config.js file that exports an object

The following examples are all the same.

• Via nxrelease key in the monorepo package.json file:

{
  "nxrelease": {
    "repositoryUrl": "https://github.com/futureverse/nx-semantic-release-sync"
  }
}

• Via .nxreleaserc YAML file:

---
repositoryUrl: 'https://github.com/futureverse/nx-semantic-release-sync'

• Via nxrelease.config.js file:

module.exports = {
  repositoryUrl: 'https://github.com/futureverse/nx-semantic-release-sync',
}

• Via CLI arguments:

$ nx semantic-release app-c --repositoryUrl "https://github.com/futureverse/nx-semantic-release-sync"

Available Options

Available Tokens

Every available option support tokens - this included nested objects and arrays.

You may see other tokens like ${nextRelease.version}, those are tokens that are replaced by semantic-release itself.

*: The replacement of tokens in plugins only occurs for plugins which are specified with options, using semantic-release's syntax For example:

plugins: [
            '@fake/plugin-without-options1',
            [
              '@semantic-release/exec',
              {
                prepareCmd: 'cp LICENSE dist/packages/${PROJECT_NAME} && cp README.md dist/packages/${PROJECT_NAME}',
                execCwd: '${WORKSPACE_DIR}',
                fakeStringArrayOption: ['${WORKSPACE_DIR}/src', '${WORKSPACE_DIR}/dist'],
                fakeBooleanOption: true,
                fakeNumberOption: 10
              }
            ],
            '@fake/plugin-without-options2',
        ]

In above example, tokens will be replaced only for @semantic-release/exec plugin, and only for its string|string[] options, others will be left untouched.

Build target

By setting buildTarget option plugin will run your build executor as part of the release, which is useful if ex. you want to publish released package to npm registry.

Skipping commits

You can skip commits for given projects using [skip $PROJECT_NAME] in its body. Ex:

  feat: update something

  [skip my-app1]
  [skip my-app2]

During analysis this commit will be skipped for release pipeline for my-app1, my-app2. You can also use [skip all] to skip commit for all projects or one single [skip my-app1, my-app2] to skip commits related to my-app1, my-app2 at once.

Alternatively you can include only particular projects in given commit by using [only $PROJECT_NAME]. Ex:

  feat: update something

  [only my-app1]
  [only my-app2]

During analysis this commit will be included only for release pipeline for my-app, my-app2. You can also use one single [skip my-app1, my-app2] to skip commits related to my-app1, my-app2 at once.

Releasing multiple apps/libraries at once

You can release multiple apps/libraries at once by using nx run-many:

npx nx run-many --target=semantic-release --parallel=false

Note: --parallel=false is required to run tasks sequentially, otherwise nx run-many will run tasks in parallel and semantic-release will fail.

Gitlab support

In order to use this plugin on Gitlab, install @semantic-release/gitlab@9.5.1 (>= 10.0.0 is not supported for now due to ES format) and set the following in your configuration file:

{
  "plugins": ["@semantic-release/gitlab"],
  "github": false
}

CI/CD

Example of GitHub actions workflow:

name: default

on:
  push:
    branches:
      - 'master'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: configure git
        run: |
          git config user.name "${GITHUB_ACTOR}"
          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"

      - run: npm ci

      - run: npx nx run my-app:semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}