1 | # **commit-analyzer**
|
2 |
|
3 | [**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to analyze commits with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
|
4 |
|
5 | [![Build Status](https://github.com/semantic-release/commit-analyzer/workflows/Test/badge.svg)](https://github.com/semantic-release/commit-analyzer/actions?query=workflow%3ATest+branch%3Amaster) [![npm latest version](https://img.shields.io/npm/v/@semantic-release/commit-analyzer/latest.svg)](https://www.npmjs.com/package/@semantic-release/commit-analyzer)
|
6 | [![npm next version](https://img.shields.io/npm/v/@semantic-release/commit-analyzer/next.svg)](https://www.npmjs.com/package/@semantic-release/commit-analyzer)
|
7 | [![npm beta version](https://img.shields.io/npm/v/@semantic-release/commit-analyzer/beta.svg)](https://www.npmjs.com/package/@semantic-release/commit-analyzer)
|
8 |
|
9 | | Step | Description |
|
10 | |------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
|
11 | | `analyzeCommits` | Determine the type of release by analyzing commits with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog). |
|
12 |
|
13 | ## Install
|
14 |
|
15 | ```bash
|
16 | $ npm install @semantic-release/commit-analyzer -D
|
17 | ```
|
18 |
|
19 | ## Usage
|
20 |
|
21 | The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):
|
22 |
|
23 | ```json
|
24 | {
|
25 | "plugins": [
|
26 | ["@semantic-release/commit-analyzer", {
|
27 | "preset": "angular",
|
28 | "releaseRules": [
|
29 | {"type": "docs", "scope":"README", "release": "patch"},
|
30 | {"type": "refactor", "release": "patch"},
|
31 | {"type": "style", "release": "patch"}
|
32 | ],
|
33 | "parserOpts": {
|
34 | "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
|
35 | }
|
36 | }],
|
37 | "@semantic-release/release-notes-generator"
|
38 | ]
|
39 | }
|
40 | ```
|
41 |
|
42 | With this example:
|
43 | - the commits that contains `BREAKING CHANGE` or `BREAKING CHANGES` in their body will be considered breaking changes.
|
44 | - the commits with a 'docs' `type`, a 'README' `scope` will be associated with a `patch` release
|
45 | - the commits with a 'refactor' `type` will be associated with a `patch` release
|
46 | - the commits with a 'style' `type` will be associated with a `patch` release
|
47 |
|
48 | **Note**: Your commits must be formatted **exactly** as specified by the chosen convention. For example the [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) require the `BREAKING CHANGE` keyword to be followed by a colon (`:`) and to be in the **footer** of the commit message.
|
49 |
|
50 | ## Configuration
|
51 |
|
52 | ### Options
|
53 |
|
54 | | Option | Description | Default |
|
55 | |----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
56 | | `preset` | [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset (possible values: [`angular`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular), [`atom`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-atom), [`codemirror`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-codemirror), [`ember`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-ember), [`eslint`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint), [`express`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-express), [`jquery`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-jquery), [`jshint`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-jshint), [`conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits)). | [`angular`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) |
|
57 | | `config` | npm package name of a custom [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset. | - |
|
58 | | `parserOpts` | Additional [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#conventionalcommitsparseroptions) options that will extends the ones loaded by `preset` or `config`. This is convenient to use a [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset with some customizations without having to create a new module. | - |
|
59 | | `releaseRules` | An external module, a path to a module or an `Array` of rules. See [`releaseRules`](#releaserules). | See [`releaseRules`](#releaserules) |
|
60 | | `presetConfig` | Additional configuration passed to the [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset. Used for example with [conventional-changelog-conventionalcommits](https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.0.0/README.md). | - |
|
61 |
|
62 | **Notes**: in order to use a `preset` it must be installed (for example to use the [eslint preset](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) you must install it with `npm install conventional-changelog-eslint -D`)
|
63 |
|
64 | **Note**: `config` will be overwritten by the values of `preset`. You should use either `preset` or `config`, but not both.
|
65 |
|
66 | **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.
|
67 |
|
68 | **Note**: For presets that expects a configuration object, such as [`conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits), the `presetConfig` option **must** be set.
|
69 |
|
70 | #### releaseRules
|
71 |
|
72 | 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](lib/default-release-rules.js) will be used if nothing matched. Those rules will be matched against the commit objects resulting of [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser) parsing. Each rule property can be defined as a [glob](https://github.com/micromatch/micromatch#matching-features).
|
73 |
|
74 | ##### Rules definition
|
75 |
|
76 | This is an `Array` of rule objects. A rule object has a `release` property and 1 or more criteria.
|
77 | ```json
|
78 | {
|
79 | "plugins": [
|
80 | ["@semantic-release/commit-analyzer", {
|
81 | "preset": "angular",
|
82 | "releaseRules": [
|
83 | {"type": "docs", "scope": "README", "release": "patch"},
|
84 | {"type": "refactor", "scope": "core-*", "release": "minor"},
|
85 | {"type": "refactor", "release": "patch"},
|
86 | {"scope": "no-release", "release": false}
|
87 | ]
|
88 | }],
|
89 | "@semantic-release/release-notes-generator"
|
90 | ]
|
91 | }
|
92 | ```
|
93 |
|
94 | ##### Rules matching
|
95 |
|
96 | 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.
|
97 |
|
98 | See [release types](lib/default-release-types.js) for the release types hierarchy.
|
99 |
|
100 | With the previous example:
|
101 | - Commits with `type` 'docs' and `scope` 'README' will be associated with a `patch` release.
|
102 | - Commits with `type` 'refactor' and `scope` starting with 'core-' (i.e. 'core-ui', 'core-rules', ...) will be associated with a `minor` release.
|
103 | - Other commits with `type` 'refactor' (without `scope` or with a `scope` not matching the glob `core-*`) will be associated with a `patch` release.
|
104 | - Commits with scope `no-release` will not be associated with a release type.
|
105 |
|
106 | ##### Default rules matching
|
107 |
|
108 | If a commit doesn't match any rule in `releaseRules` it will be evaluated against the [default release rules](lib/default-release-rules.js).
|
109 |
|
110 | With the previous example:
|
111 | - Commits with a breaking change will be associated with a `major` release.
|
112 | - Commits with `type` 'feat' will be associated with a `minor` release.
|
113 | - Commits with `type` 'fix' will be associated with a `patch` release.
|
114 | - Commits with `type` 'perf' will be associated with a `patch` release.
|
115 | - Commits with scope `no-release` will not be associated with a release type even if they have a breaking change or the `type` 'feat', 'fix' or 'perf'.
|
116 |
|
117 | ##### No rules matching
|
118 |
|
119 | If a commit doesn't match any rules in `releaseRules` or in [default release rules](lib/default-release-rules.js) then no release type will be associated with the commit.
|
120 |
|
121 | With the previous example:
|
122 | - Commits with `type` 'style' will not be associated with a release type.
|
123 | - Commits with `type` 'test' will not be associated with a release type.
|
124 | - Commits with `type` 'chore' will not be associated with a release type.
|
125 |
|
126 | ##### Multiple commits
|
127 |
|
128 | If there is multiple commits that match one or more rules, the one with the highest release type will determine the global release type.
|
129 |
|
130 | Considering the following commits:
|
131 | - `docs(README): Add more details to the API docs`
|
132 | - `feat(API): Add a new method to the public API`
|
133 |
|
134 | With the previous example the release type determined by the plugin will be `minor`.
|
135 |
|
136 | ##### Specific commit properties
|
137 |
|
138 | The properties to set in the rules will depends on the commit style chosen. For example [conventional-changelog-angular](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-angular) use the commit properties `type`, `scope` and `subject` but [conventional-changelog-eslint](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-eslint) uses `tag` and `message`.
|
139 |
|
140 | For example with `eslint` preset:
|
141 | ```json
|
142 | {
|
143 | "plugins": [
|
144 | ["@semantic-release/commit-analyzer", {
|
145 | "preset": "eslint",
|
146 | "releaseRules": [
|
147 | {"tag": "Docs", "message":"*README*", "release": "patch"},
|
148 | {"tag": "New", "release": "patch"}
|
149 | ]
|
150 | }],
|
151 | "@semantic-release/release-notes-generator"
|
152 | ]
|
153 | }
|
154 | ```
|
155 | With this configuration:
|
156 | - Commits with `tag` 'Docs', that contains 'README' in their header message will be associated with a `patch` release.
|
157 | - Commits with `tag` 'New' will be associated with a `patch` release.
|
158 | - Commits with `tag` 'Breaking' will be associated with a `major` release (per [default release rules](lib/default-release-rules.js)).
|
159 | - Commits with `tag` 'Fix' will be associated with a `patch` release (per [default release rules](lib/default-release-rules.js)).
|
160 | - Commits with `tag` 'Update' will be associated with a `minor` release (per [default release rules](lib/default-release-rules.js)).
|
161 | - All other commits will not be associated with a release type.
|
162 |
|
163 | ##### External package / file
|
164 |
|
165 | `releaseRules` can also reference a module, either by it's `npm` name or path:
|
166 | ```json
|
167 | {
|
168 | "plugins": [
|
169 | ["@semantic-release/commit-analyzer", {
|
170 | "preset": "angular",
|
171 | "releaseRules": "./config/release-rules.js"
|
172 | }],
|
173 | "@semantic-release/release-notes-generator"
|
174 | ]
|
175 | }
|
176 | ```
|
177 | ```js
|
178 | // File: config/release-rules.js
|
179 | module.exports = [
|
180 | {type: 'docs', scope: 'README', release: 'patch'},
|
181 | {type: 'refactor', scope: 'core-*', release: 'minor'},
|
182 | {type: 'refactor', release: 'patch'},
|
183 | ];
|
184 | ```
|