Skip to main content

NPM Packages Versioning

How it works​

The version is released automatically using the semantic-release utility at CI runtime. @semantic-release/commit-analyzer analyzes the commit structure and associates it with the release number <major>.<minor>.<patch>.

The commit header must contain the type: <type>: commit header

Format:​

major

  • BREAKING CHANGE: breacking changes

minor

  • feat: a new feature

patch

  • build: changes that affect the build system or external dependencies
  • ci: changes to our CI configuration files and scripts
  • docs: documentation changes
  • fix: a bug fix
  • perf: a performance fix
  • refactor: a code base improvement
  • test: a fix tests or adding missing tests

@semantic-release/git changes version property package.json and commits release assets:

{
  "version": "<major>.<minor>.<patch>"
}

Then the tag is set with a new version number.

Multiple commits​

If there are multiple commits that match one or more rules, the one with the highest release type will determine the global release type. For example:

Previous global version: 1.2.0

Two commits:

[12:32] feat: new feature
[12:40] fix: fix bug

Next global version: 1.3.0 (minor release)

Two commits:

[12:45] fix: fix bug #2
[12:50] fix: fix bug #3

Next global version: 1.3.1 (patch release)

Config​

CI​

The CI pipeline trigger of the publish task should not bind to the tag, because the tag is set in this pipeline.

Release version:

publish:
  stage: release
  script:
    - npm run build
    - npm run semantic-release
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

package.json​

{
  "scripts": {
    "semantic-release": "semantic-release"
  },
  "devDependencies": {
    "@semantic-release/git": "10.0.1",
    "semantic-release": "19.0.2"
  }
}

.releaserc.json​

@semantic-release/gitlab -> assets - list of files for npm package release.

{
  "branches": ["master"],
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "angular",
      "releaseRules": [
        {"breaking": true, "release": "major"},
        {"type": "feat", "release": "minor"},
        {"type": "fix", "release": "patch"},
        {"type": "docs", "release": "patch"},
        {"type": "refactor", "release": "patch"},
        {"type": "style", "release": "patch"},
        {"type": "build", "release": "patch"},
        {"type": "ci", "release": "patch"},
        {"type": "test", "release": "patch"},
        {"type": "perf", "release": "patch"}
      ],
      "parserOpts": {
        "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
      }
    }],
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "assets": ["package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

What else​

https://github.com/commitizen/cz-cli and/or https://github.com/conventional-changelog/commitlint tools can be used for easy commits preparation.