1 | Commit Guidelines
|
2 | =================
|
3 |
|
4 | We enforce certain rules on commits with the following goals in mind:
|
5 |
|
6 | - Be able to reliably auto-generate the `CHANGELOG.md` *without* any human
|
7 | intervention.
|
8 | - Be able to automatically and correctly increment the semver version number
|
9 | based on what was done since the last release.
|
10 | - Be able to get a quick overview of what happened to the project by glancing
|
11 | over the commit history.
|
12 | - Be able to automatically reference relevant changes from a dependency
|
13 | upgrade.
|
14 |
|
15 | Commit structure
|
16 | ----------------
|
17 |
|
18 | Each commit message consists of a header, a body and a footer. The header has a
|
19 | special format that includes a type, a scope and a subject.
|
20 |
|
21 | ```
|
22 | <type>(<scope>): <subject>
|
23 | <BLANK LINE>
|
24 | <body>
|
25 | <BLANK LINE>
|
26 | <footer>
|
27 | ```
|
28 |
|
29 | The subject should not contain more than 70 characters, including the type and
|
30 | scope, and the body should be wrapped at 72 characters.
|
31 |
|
32 | Type
|
33 | ----
|
34 |
|
35 | Must be one of the following:
|
36 |
|
37 | - `feat`: A new feature.
|
38 | - `fix`: A bug fix.
|
39 | - `minifix`: A minimal fix that doesn't warrant an entry in the CHANGELOG.
|
40 | - `docs`: Documentation only changes.
|
41 | - `style`: Changes that do not affect the meaning of the code (white-space,
|
42 | formatting, missing semi-colons, JSDoc annotations, comments, etc).
|
43 | - `refactor`: A code change that neither fixes a bug nor adds a feature.
|
44 | - `perf`: A code change that improves performance.
|
45 | - `test`: Adding missing tests.
|
46 | - `chore`: Changes to the build process or auxiliary tools and libraries.
|
47 | - `upgrade`: A version upgrade of a project dependency.
|
48 |
|
49 | Scope
|
50 | -----
|
51 |
|
52 | The scope is required for types that make sense, such as `feat`, `fix`,
|
53 | `test`, etc. Certain commit types, such as `chore` might not have a clearly
|
54 | defined scope, in which case its better to omit it.
|
55 |
|
56 | When it applies, the scope will usually by the name of the component being
|
57 | changed, e.g `feat(Form): Some great feature.
|
58 |
|
59 | A commit that changes multiple components, and makes more logical
|
60 | sense that way, might entirely omit the scope.
|
61 |
|
62 | Subject
|
63 | -------
|
64 |
|
65 | The subject should contain a short description of the change:
|
66 |
|
67 | - Use the imperative, present tense.
|
68 | - No dot (.) at the end.
|
69 |
|
70 | Footer
|
71 | ------
|
72 |
|
73 | The footer contains extra information about the commit, such as tags.
|
74 |
|
75 | **Breaking Changes** should start with the word BREAKING CHANGE: with a space
|
76 | or two newlines. The rest of the commit message is then used for this.
|
77 |
|
78 | Tags
|
79 | ----
|
80 |
|
81 | ### `See: <url>`/`Link: <url>`
|
82 |
|
83 | This tag can be used to reference a resource that is relevant to the commit,
|
84 | and can be repeated multiple times in the same commit.
|
85 |
|
86 | Resource examples include:
|
87 |
|
88 | - A link to pull requests.
|
89 | - A link to a GitHub issue.
|
90 | - A link to a website providing useful information.
|
91 | - A commit hash.
|
92 |
|
93 | Its recommended that you avoid relative URLs, and that you include the whole
|
94 | commit hash to avoid any potential ambiguity issues in the future.
|
95 |
|
96 | If the commit type equals `upgrade`, this tag should be present, and should
|
97 | link to the CHANGELOG section of the dependency describing the changes
|
98 | introduced from the previously used version.
|
99 |
|
100 | Examples:
|
101 |
|
102 | ```
|
103 | See: https://github.com/xxx/yyy/
|
104 | See: 49d89b4acebd80838303b011d30517cd6229fdbe
|
105 | Link: https://github.com/xxx/yyy/issues/zzz
|
106 | ```
|
107 |
|
108 | ### `Closes: <url>`/`Fixes: <url>`
|
109 |
|
110 | This tag is used to make GitHub close the referenced issue automatically when
|
111 | the commit is merged.
|
112 |
|
113 | Its recommended that you provide the absolute URL to the GitHub issue rather
|
114 | than simply writing the ID prefixed by a hash tag for convenience when browsing
|
115 | the commit history outside the GitHub web interface.
|
116 |
|
117 | A commit can include multiple instances of this tag.
|
118 |
|
119 | Examples:
|
120 |
|
121 | ```
|
122 | Closes: https://github.com/balena-io-modules/rendition/issues/XXX
|
123 | Fixes: https://github.com/balena-io-modules/rendition/issues/XXX
|
124 | ```
|
125 |
|
126 | ### `Change-type: <type>`
|
127 |
|
128 | This tag is used to determine the change type that a commit introduces. The
|
129 | following types are supported:
|
130 |
|
131 | - `major`
|
132 | - `minor`
|
133 | - `patch`
|
134 |
|
135 | Examples:
|
136 |
|
137 | ```
|
138 | Change-type: major
|
139 | Change-type: minor
|
140 | Change-type: patch
|
141 | ```
|
142 |
|
143 | See the [Semantic Versioning][semver] specification for a more detailed
|
144 | explanation of the meaning of these types.
|
145 |
|
146 | [semver]: http://semver.org
|