1 | # **commit-analyzer**
|
2 |
|
3 | Customizable commit-analyzer plugin for [semantic-release](https://github.com/semantic-release/semantic-release) based on [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
|
4 |
|
5 | [![Travis](https://img.shields.io/travis/semantic-release/commit-analyzer.svg)](https://travis-ci.org/semantic-release/commit-analyzer)
|
6 | [![Codecov](https://img.shields.io/codecov/c/github/semantic-release/commit-analyzer.svg)](https://codecov.io/gh/semantic-release/commit-analyzer)
|
7 | [![Greenkeeper badge](https://badges.greenkeeper.io/semantic-release/commit-analyzer.svg)](https://greenkeeper.io/)
|
8 |
|
9 | [![npm latest version](https://img.shields.io/npm/v/@semantic-release/commit-analyzer/latest.svg)](https://www.npmjs.com/package/@semantic-release/commit-analyzer)
|
10 | [![npm next version](https://img.shields.io/npm/v/@semantic-release/commit-analyzer/next.svg)](https://www.npmjs.com/package/@semantic-release/commit-analyzer)
|
11 |
|
12 | ## Options
|
13 |
|
14 | By default `commit-analyzer` uses the `angular` format described in [Angular convention](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-angular) and the [default rules](lib/default-release-rules.js) for release.
|
15 |
|
16 | Additional options can be set within the plugin definition in `package.json` to use a different commit format and to customize it:
|
17 |
|
18 | ```json
|
19 | {
|
20 | "release": {
|
21 | "analyzeCommits": {
|
22 | "preset": "angular",
|
23 | "releaseRules": [
|
24 | {"type": "docs", "scope":"README", "release": "patch"},
|
25 | {"type": "refactor", "release": "patch"},
|
26 | {"type": "style", "release": "patch"}
|
27 | ],
|
28 | "parserOpts": {
|
29 | "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
|
30 | }
|
31 | }
|
32 | }
|
33 | }
|
34 | ```
|
35 |
|
36 | | Option | Description | Default |
|
37 | |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|
|
38 | | `preset` | [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset (possible values: `angular`, `atom`, `codemirror`, `ember`, `eslint`, `express`, `jquery`, `jscs`, `jshint`). | `angular` |
|
39 | | `config` | NPM package name of a custom [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset. | - |
|
40 | | `releaseRules` | An external module, a path to a module or an `Array` of rules. See [Release rules](#release-rules). | See [Release rules](#release-rules) |
|
41 | | `parserOpts` | Additional [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#conventionalcommitsparseroptions) options that will extends ones loaded by `preset` or `config`. See [Parser options](#parser-options). | - |
|
42 |
|
43 | **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`.
|
44 |
|
45 | ### Release Rules
|
46 |
|
47 | 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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser) parsing.
|
48 |
|
49 | 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.
|
50 |
|
51 | #### Rules definition
|
52 | This is an `Array` of rule objects. A rule object has a `release` property and 1 or more criteria.
|
53 | ```json
|
54 | {
|
55 | "release": {
|
56 | "analyzeCommits": {
|
57 | "preset": "angular",
|
58 | "releaseRules": [
|
59 | {"type": "docs", "scope": "README", "release": "patch"},
|
60 | {"type": "refactor", "scope": "/core-.*/", "release": "minor"},
|
61 | {"type": "refactor", "release": "patch"}
|
62 | ]
|
63 | }
|
64 | }
|
65 | }
|
66 | ```
|
67 | #### Rules matching
|
68 |
|
69 | 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.
|
70 |
|
71 | See [release types](lib/default-release-types.js) for the release types hierarchy.
|
72 |
|
73 | With the previous example:
|
74 | - Commits with `type` 'docs' and `scope` 'README' will be associated with a `patch` release.
|
75 | - Commits with `type` 'refactor' and `scope` starting with 'core-' (i.e. 'core-ui', 'core-rules', ...) will be associated with a `minor` release.
|
76 | - Other commits with `type` 'refactor' (without `scope` or with a `scope` not matching the regexp `/core-.*/`) will be associated with a `patch` release.
|
77 |
|
78 | #### Default rules matching
|
79 |
|
80 | If a commit doesn't match any rule in `releaseRules` it will be evaluated against the [default release rules](lib/default-release-rules.js).
|
81 |
|
82 | With the previous example:
|
83 | - Commits with a breaking change will be associated with a `minor` release.
|
84 | - Commits with `type` 'feat' will be associated with a `minor` release.
|
85 | - Commits with `type` 'fix' will be associated with a `patch` release.
|
86 | - Commits with `type` 'perf' will be associated with a `patch` release.
|
87 |
|
88 | #### No rules matching
|
89 |
|
90 | 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.
|
91 |
|
92 | With the previous example:
|
93 | - Commits with `type` 'style' will not be associated with a release type.
|
94 | - Commits with `type` 'test' will not be associated with a release type.
|
95 | - Commits with `type` 'chore' will not be associated with a release type.
|
96 |
|
97 | #### Multiple commits
|
98 |
|
99 | If there is multiple commits that match one or more rules, the one with the highest release type will determine the global release type.
|
100 |
|
101 | Considering the following commits:
|
102 | - `docs(README): Add more details to the API docs`
|
103 | - `feat(API): Add a new method to the public API`
|
104 |
|
105 | With the previous example the release type determine by the plugin will be `minor`.
|
106 |
|
107 | #### Specific commit properties
|
108 |
|
109 | 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/index.js#L9-L13) 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/index.js#L9-L12) uses `tag` and `message`.
|
110 |
|
111 | For example with `eslint` preset:
|
112 | ```json
|
113 | {
|
114 | "release": {
|
115 | "analyzeCommits": {
|
116 | "preset": "eslint",
|
117 | "releaseRules": [
|
118 | {"tag": "Docs", "message":"/README/", "release": "patch"},
|
119 | {"type": "New", "release": "patch"}
|
120 | ]
|
121 | }
|
122 | }
|
123 | }
|
124 | ```
|
125 | With this configuration:
|
126 | - Commits with `tag` 'Docs', that contains 'README' in their header message will be associated with a `patch` release.
|
127 | - Commits with `tag` 'New' will be associated with a `patch` release.
|
128 | - Commits with `tag` 'Breaking' will be associated with a `major` release (per [default release rules](lib/default-release-rules.js)).
|
129 | - Commits with `tag` 'Fix' will be associated with a `patch` release (per [default release rules](lib/default-release-rules.js)).
|
130 | - Commits with `tag` 'Update' will be associated with a `minor` release (per [default release rules](lib/default-release-rules.js)).
|
131 | - Commits with `tag` 'New' will be associated with a `minor` release (per [default release rules](lib/default-release-rules.js)).
|
132 | - All other commits will not be associated with a release type.
|
133 |
|
134 | #### External package / file
|
135 |
|
136 | `releaseRules` can also reference a module, either by it's `npm` name or path:
|
137 | ```json
|
138 | {
|
139 | "release": {
|
140 | "analyzeCommits": {
|
141 | "preset": "angular",
|
142 | "releaseRules": "./config/release-rules.js"
|
143 | }
|
144 | }
|
145 | }
|
146 | ```
|
147 | ```js
|
148 | // File: config/release-rules.js
|
149 | module.exports = [
|
150 | {type: 'docs', scope: 'README', release: 'patch'},
|
151 | {type: 'refactor', scope: /core-.*/, release: 'minor'},
|
152 | {type: 'refactor', release: 'patch'},
|
153 | ];
|
154 | ```
|
155 |
|
156 | ### Parser Options
|
157 |
|
158 | Allow to overwrite specific [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#conventionalcommitsparseroptions) options. 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.
|
159 |
|
160 | The following example uses [Angular convention](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-angular/convention.md) but will consider a commit to be a breaking change if [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser) detects a valid `BREAKING CHANGE`, `BREAKING CHANGES` or `BREAKING` section in the commit body. By default the [preset](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-angular/index.js#L14) checks only for `BREAKING CHANGE` and `BREAKING CHANGES`.
|
161 |
|
162 | ```json
|
163 | {
|
164 | "release": {
|
165 | "analyzeCommits": {
|
166 | "preset": "angular",
|
167 | "parserOpts": {
|
168 | "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"],
|
169 | }
|
170 | }
|
171 | }
|
172 | }
|
173 | ```
|
174 |
|
175 | ## Usage
|
176 |
|
177 | The plugin is used by default by [semantic-release](https://github.com/semantic-release/semantic-release) so installing it is not necessary and all configuration are optionals.
|