Automate npm releases with semantic-release and human-written change logs
Making new releases is one of the most boring and tedious tasks in open source.
There are many tools that try to automate publishing and one of the most interesting is semantic-release. I was avoiding it for a long time because it makes publishing fully automated with change logs generated from commit messages, and I believe that change logs must be written by humans.
But actually it’s very flexible and I was able to customize it to do exactly what I want:
- Publish a new PATCH version to npm as soon as a fix commit merged to the
masterbranch, generate change log from commit messages.
- Postpone MINOR and MAJOR release until a proper change log is written by a project maintainer.
- Generate change log draft: Markdown file with all important commits since the latest release grouped into three sections: breaking changes, new features and bugfixes.
Below I’ll describe my own set of scripts that implements this workflow.
How it works
Semantic-release runs on a CI server.
After each successful build it analyzes new commits and see if there’s something to publish.
It determines a release type (PATCH, MINOR or MAJOR) by analyzing commit messages (more on that later).
It generates a change log:
a. If the release type is PATCH: from commit messages.
b. If the release type is MINOR or MAJOR and the latest commit is a change log: uses body of that commit as a change log.
Publishes a new version to npm.
Publishes change log to GitHub Releases page.
First install semantic-release command line tool:
Then run it in your project folder:
Enter your npm and GitHub credentials. Choose “Create no
.travis.yml” if you already have one, otherwise it will be overwritten.
Add these lines to your
You can change semantic-release behavior with plugins: detect release type, check release requirements (like a change log), generate change log, etc. I made a package with all plugins I need to support my workflow.
First install the plugins:
Then add to your
npm install and
npm run semantic-release to test if everything works. You’ll see something like that:
Which is fine and means two things: semantic-release will not make a release until it runs in a CI environment and you have no changes that could be published.
Use Git commit message convention
Each commit message consists of:
Featfor new feature,
Fixfor bug fix, etc.
- Subject: short change description.
- Body (optional): long change description.
- Footer (optional): breaking changes, GitHub issues references, etc.
Semantic-release uses this tags to find all important commits for the release (
Fix is important,
Docs is not) and determine which version (MAJOR, MINOR or PATCH) should be released.
Write change log for MINOR or MAJOR release
I wrote a script to help me with change logs.
sr-changelog. It will create a file with all important commits for the release grouped by type (breaking changes, new features and bugfixes) and open it in your default editor.
Now you can rewrite your change log to make it useful and easy to read for your users.
sr-changelog commit. It will make a commit without changes (
git commit --allow-empty) of type
Changelog and change log in the commit message body.
Publish new release
Now you need to
git push your changes and make some coffee.
Do not merge pull requests, squash them into a single commit with a proper message.
If you forget to do that and want to make a PATCH release:
- My plugins and scripts for semantic-release
- My commit message conventions
- AngularJS commit message conventions
- Why you need to write change logs yourself
- Keep a CHANGELOG: Don’t let your friends dump git logs into change logs
- Semantic Versioning