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/.