Repository files navigation

semantic-release plugin to analyze commits withconventional-changelog

$ npm install @semantic-release/commit-analyzer -D

The plugin can be configured in thesemantic-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 containsBREAKING 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 formattedexactly as specified by the chosen convention. For example theAngular Commit Message Conventions require theBREAKING CHANGE keyword to be followed by a colon (:) and to be in thefooter of the commit message.

Notes: in order to use apreset it must be installed (for example to use theeslint preset you must install it withnpm install conventional-changelog-eslint -D)

Note:config will be overwritten by the values ofpreset. You should use eitherpreset orconfig, but not both.

Note: Individual properties ofparserOpts will override ones loaded with an explicitly setpreset orconfig. Ifpreset orconfig are not set, only the properties set inparserOpts will be used.

Note: For presets that expects a configuration object, such asconventionalcommits, thepresetConfig optionmust 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 thedefault rules will be used if nothing matched. Those rules will be matched against the commit objects resulting ofconventional-commits-parser parsing. Each rule property can be defined as aglob.

This is anArray of rule objects. A rule object has arelease 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'srelease property. If a commit match multiple rules, the highest release type (major >minor >patch) is associated with the commit.

Seerelease types for the release types hierarchy.

With the previous example:

• Commits withtype 'docs' andscope 'README' will be associated with apatch release.
• Commits withtype 'refactor' andscope starting with 'core-' (i.e. 'core-ui', 'core-rules', ...) will be associated with aminor release.
• Other commits withtype 'refactor' (withoutscope or with ascope not matching the globcore-*) will be associated with apatch release.
• Commits with scopeno-release will not be associated with a release type.

If a commit doesn't match any rule inreleaseRules it will be evaluated against thedefault release rules.

With the previous example:

• Commits with a breaking change will be associated with amajor release.
• Commits withtype 'feat' will be associated with aminor release.
• Commits withtype 'fix' will be associated with apatch release.
• Commits withtype 'perf' will be associated with apatch release.
• Commits with scopeno-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 inreleaseRules or indefault release rules then no release type will be associated with the commit.

With the previous example:

• Commits withtype 'style' will not be associated with a release type.
• Commits withtype 'test' will not be associated with a release type.
• Commits withtype '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 beminor.

The properties to set in the rules will depends on the commit style chosen. For exampleconventional-changelog-angular use the commit propertiestype,scope andsubject butconventional-changelog-eslint usestag andmessage.

For example witheslint 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 withtag 'Docs', that contains 'README' in their header message will be associated with apatch release.
• Commits withtag 'New' will be associated with apatch release.
• Commits withtag 'Breaking' will be associated with amajor release (perdefault release rules).
• Commits withtag 'Fix' will be associated with apatch release (perdefault release rules).
• Commits withtag 'Update' will be associated with aminor release (perdefault release rules).
• All other commits will not be associated with a release type.

releaseRules can also reference a module, either by it'snpm name or path:

{"plugins": [    ["@semantic-release/commit-analyzer",      {"preset":"angular","releaseRules":"./config/release-rules.cjs"      }    ],"@semantic-release/release-notes-generator"  ]}

// File: config/release-rules.cjsmodule.exports=[{type:"docs",scope:"README",release:"patch"},{type:"refactor",scope:"core-*",release:"minor"},{type:"refactor",release:"patch"},];