Set up automatic CI & NPM release with semantic-release

April 10, 2018
4:40 pm

Setup

Setup semantic-release in your project is pretty easy:

npx semantic-release-cli setup

then you will be asked about your npm and github credentials

In terms of travis CI, it will setup the integration with github and the environment variables.

Release a new version

release a new version is easy, but still you need to notice:

it only happens on master by default (you can customize the configuration)
new release will only be made when you have commits followed special format, for examples: feat(pencil): add 'graphiteWidth' option

A built with a new release can be seen here:

[Semantic release]: Analyzing commit: fix(test): update fix test
[Semantic release]: The release type for the commit is patch
[Semantic release]: Analyzing commit: init
[Semantic release]: The commit should not trigger a release
[Semantic release]: Analyzing commit: Initial commit
[Semantic release]: The commit should not trigger a release
[Semantic release]: Analysis of 3 commits complete: patch release
[Semantic release]: There is no previous release, the next release version is 1.0.0
[Semantic release]: Call plugin verify-release
[Semantic release]: Call plugin generateNotes
[Semantic release]: Call plugin prepare
[Semantic release]: Wrote version 1.0.0 to package.json
[Semantic release]: Wrote version 1.0.0 to package-lock.json
[Semantic release]: Found 2 file(s) to commit
[Semantic release]: Creating tag v1.0.0
[Semantic release]: Prepared Git release: v1.0.0
[Semantic release]: Call plugin generateNotes
[Semantic release]: Create tag v1.0.0
[Semantic release]: Call plugin publish
[Semantic release]: Publishing version 1.0.0 to npm registry
+ semantic-release-test-repo@1.0.0[Semantic release]: Published GitHub release: https://github.com/neekey/semantic-release-test-repo/releases/tag/v1.0.0
[Semantic release]: Published release: 1.0.0

semantic-release will create a tag back to your repo, and a new version of npm package is ready, but by default, semantic-release will not update the version of package.json back to your repo

Update `package.json` version

To enable this feature, we need a semantic-release plugin: https://github.com/semantic-release/git

To use the plugin, we need to:

npm i @semantic-release/git

and then update the config in /path_to_your_project/.releaserc (create one):

{
  "prepare": [
    "@semantic-release/npm",
    {
      "path": "@semantic-release/git",
      "assets": [
        "package.json",
        "package-lock.json"
      ],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }
  ]
}

if you trigger a new release again, you should be able to see an automatic commit back to your repo to do the update.

Am I Satisfied?

The little tutorial above seems quite simple, but for a realy project maintainer, I am not 100% satisfied about semantic-release for several reasons:

Its documentation is not well enough, I still find myself spending a lot time digging around
The commits format based strategy is too strict, it will be quite tedious if you have to ask your contributors to commit their commit with special format
It does not support multiple CI buids, for example I have both Travis and Appveyor, semantic-release is not able to tell if both of the CIs have passed.

The workflow I want

To be honest, I total understand the intention of semantic-release’s strict rules, which follows the best practice. but for me and a lot small project, we just need some tool that is easy to use and understand.

A tool with following features sounds more than enough to me:

can do NPM release on master and use whatever in package.json as the new version number. it’s more predictable and flexible.
can create a tag using the version number as name and collect tag commits (no format required, just list them)

with a tool like this, i can simplely setup a workflow like bellow:

Branchs

master

master always reflects the lastest package on NPM, and is the only branch that will trigger a new release

release/x.y.z

once a new release is ready, I will create a new release branch and bump a new version for it. if everything for the new release ready, I can just merge it to master.

develop

a daily used development branch. can be used to accept PR from contributors. Once I have accumulated enough updates, I can create a release branch from develop.