The semantic-release tool is used to automatically determine the next version of the project and publish a release in the GitHub project as well as release it to the @NordicSemiconductor
npm organization.
The next version is determined by scanning the commit messages. The commit messages must follow the Angular commit message rules, and in every library a hook will check the commit messages against these rules.
Note
The package.json
file of a project must contain only 0.0.0-development
as the version
property. Semantic-release will ignore the value. Only the published package on npm will contain the correct version number.
Consider an example of a library, which has npm version 2.3.4
.
A new version will be published by the respective project's CI run. Use commit messages that follow the schema for a commit message.
Examples of commit messages that trigger a release:
Patch release
fix: commit message
Feature release
feat: commit message
Breaking release
scope: commit message
BREAKING CHANGE:
description of breaking change
Note
A commit message with different format will not trigger a release.
A fix is a change to the implementation, which removes a bug without changing the public API (method names and signatures, exports) of the library. The consumer of the library does not need to change their implementation when installing the fixed version.
To release a fix (that updates the version from 2.3.4
to 2.3.5
), use the type fix
in the commit message:
fix: commit message
You can optionally add a scope, which is a lowercase string that is used to identify the affected component.
fix(scope): commit message
Scopes are useful when working with a large project.
A feature is a change to the implementation of a library which adds additional functionality without changing the public API of the library.
You may add new exports, methods and extra method arguments that are optional, but the consumer of the library does not need to change their implementation when installing the library with the new feature.
To release a feature (that updates the version from 2.3.4
to 2.4.0
), use the type feat
in the commit message:
feat: commit message
You can optionally add a scope as well.
Whenever the public API of the library changes in a way that requires the consumer to update their implementation, you must mark the change as breaking. This can happen in the following conditions:
- Method names and arguments are renamed.
- Previously optional arguments become mandatory.
- Arguments are removed.
- Classes are renamed.
Even if the change is very small, as soon as you break the library's contract (its public API), it is a breaking change according to Semantic Versioning 2.0.0.
To do a breaking release (that updates the version from 2.3.4
to 3.0.0
), use the text BREAKING CHANGE:
(followed by a space of two new lines) in the commit message:
refactor: commit message
BREAKING CHANGE:
description of breaking change
You can optionally add a scope as well.
In the case of a breaking release, the message type (refactor
in the example) can be any valid type.
Some of the typical changes that you make on the repository are updating the dependencies or refactoring.
If you are manually updating the dependencies in a library, you must commit the change as a fix, so that the consumers also use the updated dependencies.
If you perform a pure refactoring of a library without changing the features and the public API and if you require the refactored version in your consumers, commit the refactoring as a feature. In this case, you are improving the library, which qualifies as a feature. For example, a performance improvement can be a feature.
After you have pushed your changes to the remote repository, a job will be run on the CI runner. If the job completes successfully (for example, all the tests pass and the linter does not report any errors), semantic-release
will determine the next version to be released.
The highest commit takes precedence (fix
> feat
> breaking change
). This means that if the list of commit messages since the last release contains only fixes, the patch version will be incremented (2.3.4 -> 2.3.5
). If the list of commits contains at least one new feature, then the minor version will be incremented and the patch version will be set to 0
(2.3.4 -> 2.4.0
). If the list of commits contains at least one breaking change, then the major version will be incremented, and the minor and patch versions will be set to 0
(2.3.4 -> 3.0.0
).