|
14 | 14 | - [Code](#code) |
15 | 15 | - [Dev environment](#dev-environment) |
16 | 16 | - [Commiting](#commiting) |
| 17 | + - [Why all this rules?](#why-all-this-rules) |
17 | 18 | - [Submitting a pull request](#submitting-a-pull-request) |
18 | 19 |
|
19 | 20 | ## Getting started |
@@ -118,45 +119,88 @@ This project uses [Prettier](http://prettier.io/) for code formatting. Consider |
118 | 119 |
|
119 | 120 | ## Commiting |
120 | 121 |
|
121 | | -- Never use the `-m <msg>` / `--message=<msg>` flag to `git commit`; |
| 122 | +A commit message can consists of a **header**, **body** and **footer**. The header is the only mandatory part and consists of a type and a subject. The body is used to fully describe the change. The footer is the place to reference any issues or pull requests related to the commit. That said, we end with a template like this: |
| 123 | + |
| 124 | +``` |
| 125 | +<type>: <subject> |
| 126 | +
|
| 127 | +[optional body] |
| 128 | +
|
| 129 | +[optional footer] |
| 130 | +``` |
| 131 | + |
| 132 | +To ensure that a commit is valid, easy to read, and changelog-ready, we have a hook that lints the commit message before allowing a commit to pass. This linter verifies the following: |
| 133 | + |
| 134 | +- The header (first line) is the only mandatory part of the commit message; |
| 135 | +- The body and footer are both optional but its use is highly encouraged; |
| 136 | +- The header should contains: |
| 137 | + - A type: |
| 138 | + - Must be lowercase; |
| 139 | + - Must be one of: |
| 140 | + - **chore**: A change that neither fix a bug nor adds a feature; |
| 141 | + - **ci**: A CI change; |
| 142 | + - **docs**: A documentation change or fix; |
| 143 | + - **feat**: A new feature; |
| 144 | + - **fix**: A bug fix; |
| 145 | + - **test**: A test-related change. |
| 146 | + - A subject: |
| 147 | + - Must be capitalized; |
| 148 | + - Must be limited to 50 characters or less; |
| 149 | + - Must omit any trailing punctuation. |
| 150 | +- The body: |
| 151 | + - Must have a leading blank line; |
| 152 | + - Each line must be limited to 72 characters or less. |
| 153 | +- The footer: |
| 154 | + - Must have a leading blank line; |
| 155 | + - Each line must be limited to 72 characters or less; |
| 156 | + - If needed, reference to issues and pull requests must be made here in the last line. |
| 157 | + |
| 158 | +You also should follow these general guidelines when committing: |
| 159 | + |
122 | 160 | - Use the present tense ("Add feature" not "Added feature"); |
123 | 161 | - Use the imperative mood ("Move cursor to..." not "Moves cursor to..."); |
124 | | -- The first line should: |
125 | | - - Be capitalized; |
126 | | - - Have 50 characters or less; |
127 | | - - Omit any trailing punctuation; |
128 | | - - Be followed by a blank line. |
129 | | -- The following lines should have 72 characters or less; |
130 | | -- Reference issues and pull requests liberally after the first line; |
131 | | -- When creating a commit try to answer the following questions: |
| 162 | +- Try to answer the following questions: |
132 | 163 | - Why is this change necessary? |
133 | 164 | - How does it address the issue? |
134 | 165 | - What side effects (if any) does this change may have? |
135 | 166 |
|
136 | | -Example: |
| 167 | +Example of a commit message: |
137 | 168 |
|
138 | 169 | ``` |
139 | | -Commit message style guide for Git |
| 170 | +type: Commit message style guide for Git |
140 | 171 |
|
141 | 172 | The first line of a commit message serves as a summary. When displayed |
142 | 173 | on the web, it's often styled as a heading, and in emails, it's |
143 | | -typically used as the subject. As such, you should capitalize it and |
| 174 | +typically used as the subject. As such, you should specify a "type" and |
| 175 | +a "subject". The type must be lowercase and one of: chore, ci, docs, |
| 176 | +feat, fix, test. For the subject you'll need capitalize it and |
144 | 177 | omit any trailing punctuation. Aim for about 50 characters, give or |
145 | 178 | take, otherwise it may be painfully truncated in some contexts. Write |
146 | | -it, along with the rest of your message, in the present tense and imperative mood: "Fix |
147 | | -bug" and not "Fixed bug" or "Fixes bug". Consistent wording makes it |
148 | | -easier to mentally process a list of commits. |
| 179 | +it, along with the rest of your message, in the present tense and |
| 180 | +imperative mood: "Fix bug" and not "Fixed bug" or "Fixes bug". |
| 181 | +Consistent wording makes it easier to mentally process a list of |
| 182 | +commits. |
149 | 183 |
|
150 | | -Oftentimes a subject by itself is sufficient. When it's not, add a |
| 184 | +Oftentimes a subject by itself is sufficient. When it's not, add a |
151 | 185 | blank line (this is important) followed by one or more paragraphs hard |
152 | | -wrapped to 72 characters. Git is strongly opinionated that the author |
| 186 | +wrapped to 72 characters. Git is strongly opinionated that the author |
153 | 187 | is responsible for line breaks; if you omit them, command line tooling |
154 | 188 | will show it as one extremely long unwrapped line. Fortunately, most |
155 | 189 | text editors are capable of automating this. |
156 | 190 |
|
157 | | -When relevant, issues and pull request can be referenced using theirs numbers: #3 #12 |
| 191 | +Issues and pull request can be referenced on the footer: #3 #12 |
158 | 192 | ``` |
159 | 193 |
|
| 194 | +### Why all these rules? |
| 195 | + |
| 196 | +We try to enforce these rules for the following reasons: |
| 197 | + |
| 198 | +- Automatically generating changelog; |
| 199 | +- Communicating in a better way the nature of changes; |
| 200 | +- Triggering build and publish processes; |
| 201 | +- Automatically determining a semantic version bump (based on the types of commits); |
| 202 | +- Making it easier for people to contribute, by allowing them to explore a more structured commit history. |
| 203 | + |
160 | 204 | ## Submitting a pull request |
161 | 205 |
|
162 | 206 | Before submitting a pull request, please make sure the following is done: |
@@ -165,4 +209,6 @@ Before submitting a pull request, please make sure the following is done: |
165 | 209 | - Example: `feature/my-awesome-feature` or `fix/annoying-bug`; |
166 | 210 | - Run `yarn` in the repository root; |
167 | 211 | - If you’ve fixed a bug or added code that should be tested, **add tests**; |
168 | | -- Ensure the test suite passes. |
| 212 | +- Ensure the test suite passes; |
| 213 | +- Ensure your commit is validated; |
| 214 | +- If your pull request is about documentation or meta files, please add the tag **[skip ci]** in the title. |