| 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
|