Customizable commit-analyzer plugin for semantic-release based on conventional-changelog
By default commit-analyzer
uses the angular
format described in Angular convention.
Additionnal options can be set within the plugin definition in package.json
to use a different commit format and to customize it:
{
"release": {
"analyzeCommits": {
"preset": "angular",
"releaseRules": [
{"type": "docs", "scope":"README", "release": "patch"},
{"type": "refactor", "release": "patch"},
{"type": "style", "release": "patch"}
],
"parserOpts": {
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
}
}
}
}
Option | Description | Default |
---|---|---|
preset |
conventional-changelog preset (possible values: angular , atom , codemirror , ember , eslint , express , jquery , jscs , jshint ). |
angular |
config |
NPM package name of a custom conventional-changelog preset. | - |
releaseRules |
An external module, a path to a module or an Array of rules. See Release rules. |
See Release rules |
parserOpts |
Additional conventional-commits-parser options that will extends ones loaded by preset or config . See Parser options. |
- |
NOTE: config
will be overwritten by the values of preset
. You should use either preset
or config
, but not both. Individual properties of parserOpts
will overwrite ones loaded with preset
or config
.
This is an Array
of rule objects. A rule object has a release
property and 1 or more criteria.
{
"release": {
"analyzeCommits": {
"preset": "angular",
"releaseRules": [
{"type": "docs", "scope": "README", "release": "patch"},
{"type": "refactor", "scope": "/core-.*/", "release": "minor"},
{"type": "refactor", "release": "patch"}
]
}
}
}
Each commit will be compared with each rule and when it matches, the commit will be associated with the release type in the rule's release
property. If a commit match multiple rules, the highest release type (major
> minor
> patch
) is associated with the commit.
See release types for the release types hierarchy.
With the previous example:
- Commits with
type
'docs' andscope
'README' will be associated with apatch
release. - Commits with
type
'refactor' andscope
starting with 'core-' (i.e. 'core-ui', 'core-rules', ...) will be associated with aminor
release. - Other commits with
type
'refactor' (withoutscope
or with ascope
not matching the regexp/core-.*/
) will be associated with apatch
release.
If a commit doesn't match any rule in releaseRules
it will be evaluated agaisnt the default release rules.
With the previous example:
- Commits with a breaking change will be associated with a
minor
release. - Commits with
type
'feat' will be associated with aminor
release. - Commits with
type
'fix' will be associated with apatch
release. - Commits with
type
'perf' will be associated with apatch
release.
If a commit doesn't match any rules in releaseRules
or in default release rules then no release type will be associated with the commit.
With the previous example:
- Commits with
type
'style' will not be associated with a release type. - Commits with
type
'test' will not be associated with a release type. - Commits with
type
'chore' will not be associated with a release type.
If there is multiple commits that match one or more rules, the one with the highest realease type will determine the global release type.
Considering the following commits:
docs(README): Add more details to the API docs
feat(API): Add a new method to the public API
With the previous example the release type determine by the plugin will be minor
.
The properties to set in the rules will depends on the commit style choosen. For example conventional-changelog-angular use the commit properties type
, scope
and subject
but conventional-changelog-eslint uses tag
and message
.
For example with eslint
preset:
{
"release": {
"analyzeCommits": {
"preset": "eslint",
"releaseRules": [
{"tag": "Docs", "message":"/README/", "release": "patch"},
{"type": "New", "release": "patch"}
]
}
}
}
With this configuration:
- Commits with
tag
'Docs', that contains 'README' in their header message will be associated with apatch
release. - Commits with
tag
'New' will be associated with apatch
release. - Commits with
tag
'Breaking' will be associated with amajor
release (per default release rules). - Commits with
tag
'Fix' will be associated with apatch
release (per default release rules). - Commits with
tag
'Update' will be associated with aminor
release (per default release rules). - Commits with
tag
'New' will be associated with aminor
release (per default release rules). - All other commits will not be associated with a release type.
releaseRules
can also reference a module, either by it's npm
name or path:
{
"release": {
"analyzeCommits": {
"preset": "angular",
"releaseRules": "./config/release-rules.js"
}
}
}
// File: config/release-rules.js
module.exports = [
{type: 'docs', scope: 'README', release: 'patch'},
{type: 'refactor', scope: /core-.*/, release: 'minor'},
{type: 'refactor', release: 'patch'},
];
Allow to overwrite specific conventional-commits-parser options. This is convenient to use a conventional-changelog preset with some customizations without having to create a new module.
The following example uses Angular convention but will consider a commit to be a breaking change if it's body contains BREAKING CHANGE
, BREAKING CHANGES
or BREAKING
. By default the preset checks only for BREAKING CHANGE
and BREAKING CHANGES
.
{
"release": {
"analyzeCommits": {
"preset": "angular",
"parserOpts": {
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"],
}
}
}
}