Best practices (or, why these practices)

On semantic-release

semantic-release is a utility to automate certain aspects of software releases--for npm based packages, as far as I know.

It takes the git log messages (formatted in a special way) and generates a new version number for the package. The increment in version number depends on the type of change, following semver. If it's a documentation change, only the patch number will increase. If there are backwards compatible changes (e.g. a new feature) the minor number will increase. Breaking changes should increase the major number.

This automatic process is started when a new commit is pushed to GitHub. Tests for the package are run in TravisCI, and if the tests pass, the new release number is calculated. A copy of the project is checked out in the TravisCI container, and the new release written to the version field in package.json. Then:

  • this is published to npm, with the newly created version in package.json
  • that git commit is tagged with the release number
  • a new release (i.e. a ZIP file) is created in GitHub so people can download it instead of installing it via npm
  • The release also contains an automatically generated release log. E.g. this
Benefits of using this system:

  • It's automated
  • I won't forget to do all the tagging and publishing process which is always the same
  • There is no npm publishing if the tests fail (so no publishing a thing that breaks)
  • Version numbers are guaranteed to be different

Types of commits

Syntax is <type_of_commit>: <commit log message as usual>.
  • fix (fix bugs but do not break the API)
  • style (e.g. formatting changes)
  • docs (adding/removing/changing docs)
  • refactor (rewriting code but not breaking changes, or adding features or fixing bugs)
  • test (changes in tests, e.g. adding a missing one)
  • feat (adding new features which do not break API) -- Increases MINOR field
  • BREAKING CHANGE -- Increases MAJOR field
All the commits increase the PATCH field except where noted. (This is the AngularJS convention)

Adding semantic-release to your workflow

First install the global cli utility:


npm install -g semantic-release-cli

Then in an existing node.js based project (i.e. a package.json already exists):


semantic-release-cli setup

It will ask you a series of questions to set up semantic-release on the project. If all goes well, the next time you push to GitHub, a new release will automatically happen.

You will need to have TravisCI enabled in your account!

Quirks

By default semantic-release removes the version field in package.json, but that makes it impossible to install npm packages using the git protocol. The solution is to have a "bogus" version number such as "0.0.0-development". This value is replaced with the actual version number before publishing to npm or GitHub releases, as described above.