Setup
Setup semantic-release in your project is pretty easy:
|
1 2 |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
[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:
|
1 2 |
npm i @semantic-release/git |
and then update the config in /path_to_your_project/.releaserc (create one):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "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.jsonas 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/.