semantic-release plugin to analyze commits with conventional-changelog
Step | Description |
---|---|
analyzeCommits |
Determine the type of release by analyzing commits with conventional-changelog. |
$ npm install @semantic-release/commit-analyzer -D
The plugin can be configured in the semantic-release configuration file:
{
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "angular",
"releaseRules": [
{"type": "docs", "scope":"README", "release": "patch"},
{"type": "refactor", "release": "patch"},
{"type": "style", "release": "patch"}
],
"parserOpts": {
"noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
}
}],
"@semantic-release/release-notes-generator"
]
}
With this example:
- the commits that contains
BREAKING CHANGE
orBREAKING CHANGES
in their body will be considered breaking changes. - the commits with a 'docs'
type
, a 'README'scope
will be associated with apatch
release - the commits with a 'refactor'
type
will be associated with apatch
release - the commits with a 'style'
type
will be associated with apatch
release
Note: Your commits must be formatted exactly as specified by the chosen convention. For example the Angular Commit Message Conventions require the BREAKING CHANGE
keyword to be followed by a colon (:
) and to be in the footer of the commit message.
Option | Description | Default |
---|---|---|
preset |
conventional-changelog preset (possible values: angular , atom , codemirror , ember , eslint , express , jquery , jshint , conventionalcommits ). |
angular |
config |
npm package name of a custom conventional-changelog preset. | - |
parserOpts |
Additional conventional-commits-parser options that will extends the ones loaded by preset or config . This is convenient to use a conventional-changelog preset with some customizations without having to create a new module. |
- |
releaseRules |
An external module, a path to a module or an Array of rules. See releaseRules . |
See releaseRules |
presetConfig |
Additional configuration passed to the conventional-changelog preset. Used for example with conventional-changelog-conventionalcommits. | - |
Notes: in order to use a preset
it must be installed (for example to use the eslint preset you must install it with npm install conventional-changelog-eslint -D
)
Note: config
will be overwritten by the values of preset
. You should use either preset
or config
, but not both.
Note: Individual properties of parserOpts
will override ones loaded with an explicitly set preset
or config
. If preset
or config
are not set, only the properties set in parserOpts
will be used.
Note: For presets that expects a configuration object, such as conventionalcommits
, the presetConfig
option must be set.
Release rules are used when deciding if the commits since the last release warrant a new release. If you define custom release rules the default rules will be used if nothing matched. Those rules will be matched against the commit objects resulting of conventional-commits-parser parsing.
This is an Array
of rule objects. A rule object has a release
property and 1 or more criteria.
{
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "angular",
"releaseRules": [
{"type": "docs", "scope": "README", "release": "patch"},
{"type": "refactor", "scope": "/core-.*/", "release": "minor"},
{"type": "refactor", "release": "patch"},
{"scope": "no-release", "release": false}
]
}],
"@semantic-release/release-notes-generator"
]
}
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. - Commits with scope
no-release
will not be associated with a release type.
If a commit doesn't match any rule in releaseRules
it will be evaluated against the default release rules.
With the previous example:
- Commits with a breaking change will be associated with a
major
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. - Commits with scope
no-release
will not be associated with a release type even if they have a breaking change or thetype
'feat', 'fix' or 'perf'.
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 release 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 determined by the plugin will be minor
.
The properties to set in the rules will depends on the commit style chosen. 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:
{
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "eslint",
"releaseRules": [
{"tag": "Docs", "message":"/README/", "release": "patch"},
{"tag": "New", "release": "patch"}
]
}],
"@semantic-release/release-notes-generator"
]
}
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). - 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:
{
"plugins": [
["@semantic-release/commit-analyzer", {
"preset": "angular",
"releaseRules": "./config/release-rules.js"
}],
"@semantic-release/release-notes-generator"
]
}
// File: config/release-rules.js
module.exports = [
{type: 'docs', scope: 'README', release: 'patch'},
{type: 'refactor', scope: /core-.*/, release: 'minor'},
{type: 'refactor', release: 'patch'},
];