Have ideas to improve npm?Join in the discussion! »

    @orchestrator/semantic-release-monorepo

    6.2.3 • Public • Published

    semantic-release-monorepo

    Build Status npm semantic-release

    Apply semantic-release's automatic publishing to a monorepo.

    Extra Config

    This fork adds config --fixedMode true that allows to stop filtering commits by file paths.

    It is useful for monorepos where all packages must be released with the same version.

    Why

    The default configuration of semantic-release assumes a one-to-one relationship between a GitHub repository and an npm package.

    This set of plugins 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 a merge may release multiple package versions.

    In order to avoid version collisions, release git tags are namespaced using the given package's name: <package-name>-<version>.

    Install

    npm install -D semantic-release @orchestrator/semantic-release-monorepo

    Usage

    Run semantic-release-monorepo for the package in the current working directory:

    npx semantic-release -e @orchestrator/semantic-release-monorepo

    It helps to think about semantic-release-monorepo as a variation on semantic-release's default behavior, using the latter's plugin system to adapt it to work with a monorepo.

    With Lerna

    The monorepo management tool lerna can be used to run semantic-release-monorepo across all packages in a monorepo:

    lerna exec --concurrency 1 -- npx --no-install semantic-release -e @orchestrator/semantic-release-monorepo

    Note that this requires installing semantic-release and semantic-release-monorepo for each package.

    Alternatively, 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.

    Configuration

    The set of plugins in this package wrap other semantic-release plugins to modify their behavior. By default, the same plugin configuration as semantic-release is used, but any plugin configuration should be compatible.

    Release config

    Plugins can be configured in the release config, with one important caveat:

    Due to limitations in how plugins may be composed (discussion), semantic-release-monorepo must unfortunately "hard-code" the set of plugins it wraps: analyze-commits and generateNotes.

    Users may still want to define a custom versions of the plugin set, or want to pass options to the default versions. To work around this problem, set the desired plugin configuration under the monorepo property instead.

    Example of use with non-default set of plugins

    package.json

    {
      "release": {
        "monorepo": {
          "analyzeCommits": {
            "format": "atom"
          },
          "generateNotes": "myNotesGenerator"
        },
        "prepare": ["@semantic-release/npm", "@semantic-release/git"],
        "verifyConditions": ["@semantic-release/git"]
      }
    }

    Performance

    Naturally, the more packages in a monorepo, the longer it takes semantic-release to run against all of them. If total runtime becomes a problem, consider the following optimization:

    Reduce expensive network calls (50%+ runtime reduction)

    By default, semantic-release's verifyConditions plugin configuration contains @semantic-release/npm and @semantic-release/github. These two plugins each make a network call to verify that credentials for the respective services are properly configured. When running in a monorepo, these verifications will be redundantly repeated for each and every package, greatly contributing to overall runtime. Optimally, we'd only want make these verification calls one time.

    By moving these plugins to the verifyRelease configuration, they will only run if semantic-release determines a release is to be made for a given package (at a time when the given verifications are actually relevant). Likely, most times semantic-release is run over a monorepo, only a small subset of all packages trigger releases.

    NOTE: To allow for dynamic code, this example defines the release configuration in .releaserc.js instead of inside of package.json.

    module.exports = {
      verifyConditions: [],
      verifyRelease: ['@semantic-release/npm', '@semantic-release/github']
        .map(require)
        .map(x => x.verifyConditions),
    };

    Advanced

    The set of semantic-release-monorepo plugins wrap the default semantic-release workflow, augmenting it to work with a monorepo.

    analyzeCommits

    • Filters the repo commits to only include those that touched files in the given monorepo package.

    generateNotes

    • Filters the repo commits to only include those that touched files in the given monorepo package.

    • Maps the version field of nextRelease to use the monorepo git tag format. The wrapped (default) generateNotes implementation uses version 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 @orchestrator/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).

    Keywords

    none

    Install

    npm i @orchestrator/semantic-release-monorepo

    DownloadsWeekly Downloads

    0

    Version

    6.2.3

    License

    MIT

    Unpacked Size

    16.5 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar