|
| 1 | +# Git Commit Message Convention |
| 2 | + |
| 3 | +> This is adapted from [Angular's commit convention](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular). |
| 4 | +
|
| 5 | +## TL;DR |
| 6 | + |
| 7 | +Messages must be matched by the following regex: |
| 8 | + |
| 9 | +``` js |
| 10 | +/^(Revert: )?(Feature|Fix|Docs|Improve|Config|Example|Refactor|Style|Test|Build|CI)(\(.+\))?: .{1,80}/ |
| 11 | +``` |
| 12 | + |
| 13 | +## Commit Message Format |
| 14 | + |
| 15 | +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special format that includes a **type**, a **scope** and a **subject**: |
| 16 | + |
| 17 | +```text |
| 18 | +<type>(<scope>): <subject> |
| 19 | +<BLANK LINE> |
| 20 | +<body> |
| 21 | +<BLANK LINE> |
| 22 | +<footer> |
| 23 | +``` |
| 24 | + |
| 25 | +The **header** is mandatory and the **scope** of the header is optional. |
| 26 | + |
| 27 | +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier |
| 28 | +to read on GitHub as well as in various git tools. |
| 29 | + |
| 30 | +The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any. |
| 31 | + |
| 32 | +Samples: (even more [samples](https://github.com/Armour/vue-typescript-admin-template/commits/master)) |
| 33 | + |
| 34 | +```text |
| 35 | +Docs(changelog): update changelog to beta.5 |
| 36 | +``` |
| 37 | + |
| 38 | +```text |
| 39 | +Feature($browser): onUrlChange event (popstate/hashchange/polling) |
| 40 | +
|
| 41 | +Added new event to $browser: |
| 42 | +- forward popstate event if available |
| 43 | +- forward hashchange event if popstate not available |
| 44 | +- do polling when neither popstate nor hashchange available |
| 45 | +
|
| 46 | +Breaks $browser.onHashChange, which was removed (use onUrlChange instead) |
| 47 | +``` |
| 48 | + |
| 49 | +```text |
| 50 | +Fix(release): need to depend on latest rxjs and zone.js |
| 51 | +
|
| 52 | +The version in our package.json gets copied to the one we publish, and users need the latest of these. |
| 53 | +
|
| 54 | +Closes #123, #245, #992 |
| 55 | +
|
| 56 | +BREAKING CHANGE: isolate scope bindings definition has changed and |
| 57 | +the inject option for the directive controller injection was removed. |
| 58 | +
|
| 59 | +To migrate the code follow the example below: |
| 60 | +
|
| 61 | +Before: |
| 62 | +
|
| 63 | +scope: { |
| 64 | + myAttr: 'attribute', |
| 65 | + myBind: 'bind', |
| 66 | + myExpression: 'expression', |
| 67 | + myEval: 'evaluate', |
| 68 | + myAccessor: 'accessor' |
| 69 | +} |
| 70 | +
|
| 71 | +After: |
| 72 | +
|
| 73 | +scope: { |
| 74 | + myAttr: '@', |
| 75 | + myBind: '@', |
| 76 | + myExpression: '&', |
| 77 | + // myEval - usually not useful, but in cases where the expression is assignable, you can use '=' |
| 78 | + myAccessor: '=' // in directive's template change myAccessor() to myAccessor |
| 79 | +} |
| 80 | +
|
| 81 | +The removed `inject` wasn't generaly useful for directives so there should be no code using it. |
| 82 | +``` |
| 83 | + |
| 84 | +### Revert |
| 85 | + |
| 86 | +If the commit reverts a previous commit, it should begin with `Revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted. |
| 87 | + |
| 88 | +### Type |
| 89 | + |
| 90 | +Must be one of the following: |
| 91 | + |
| 92 | +* **Build**: Changes that affect the build system or external dependencies (example scopes: gulp, npm, yarn) |
| 93 | +* **CI**: Changes to CI related configuration files and scripts (example scopes: travis, circle, browserstack) |
| 94 | +* **Config**: Changes to other configuration files (example scopes: webpack, babel, docker) |
| 95 | +* **Docs**: Documentation only changes (example scopes: readme, changelog) |
| 96 | +* **Example**: Changes for example code |
| 97 | +* **Feature**: A new feature |
| 98 | +* **Fix**: A bug fix |
| 99 | +* **Improve**: Backwards-compatible enhancement changes |
| 100 | +* **Refactor**: A code change that neither fixes a bug nor adds a feature |
| 101 | +* **Style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
| 102 | +* **Test**: Changes for testing code |
| 103 | + |
| 104 | +If the prefix is `Feature` or `Fix`, it will appear in the changelog. However if there is any [BREAKING CHANGE](#footer), the commit will always appear in the changelog. |
| 105 | + |
| 106 | +### Scope |
| 107 | + |
| 108 | +The scope could be anything specifying place of the commit change. For example `core`, `compiler`, `ssr`, `v-model`, `transition` etc... |
| 109 | + |
| 110 | +### Subject |
| 111 | + |
| 112 | +The subject contains succinct description of the change: |
| 113 | + |
| 114 | +* use the imperative, present tense: "change" not "changed" nor "changes" |
| 115 | +* don't capitalize the first letter |
| 116 | +* no dot (.) at the end |
| 117 | + |
| 118 | +### Body |
| 119 | + |
| 120 | +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". |
| 121 | +The body should include the motivation for the change and contrast this with previous behavior. |
| 122 | + |
| 123 | +### Footer |
| 124 | + |
| 125 | +The footer should contain any information about **Breaking Changes** and is also the place to |
| 126 | +reference GitHub issues that this commit **Closes**. |
| 127 | + |
| 128 | +**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this. |
| 129 | + |
| 130 | +A detailed explanation can be found in this [document](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit) |
0 commit comments