Set up automatic CI & NPM release with semantic-release

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.

feature/feature_name

a independent feature branch, once ready can be merged to develop.

The whole idea is from http://nvie.com/posts/a-successful-git-branching-model/.

Leave a Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.