mirror of
https://github.com/xHyroM/roles-bot.git
synced 2024-11-09 19:08:05 +01:00
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
## <a name="commit"></a> Commit Message Format
|
|
|
|
_This specification is inspired by and supersedes the [Brainclements commit message format](https://gist.github.com/brianclements/841ea7bffdb01346392c)._
|
|
|
|
We have very precise rules over how our Git commit messages must be formatted.
|
|
This format leads to **easier to read commit history**.
|
|
|
|
Each commit message consists of a **header**, a **body**, and a **footer**.
|
|
|
|
```
|
|
<header>
|
|
<BLANK LINE>
|
|
<body>
|
|
<BLANK LINE>
|
|
<footer>
|
|
```
|
|
|
|
The `header` is mandatory and must conform to the [Commit Message Header](#commit-header) format.
|
|
|
|
The `body` is mandatory for all commits except for those of type "docs".
|
|
When the body is present it must be at least 20 characters long and must conform to the [Commit Message Body](#commit-body) format.
|
|
|
|
The `footer` is optional. The [Commit Message Footer](#commit-footer) format describes what the footer is used for and the structure it must have.
|
|
|
|
#### <a name="commit-header"></a>Commit Message Header
|
|
|
|
```
|
|
<type>(<scope>)(!?): <short summary>
|
|
│ │ │ │
|
|
│ │ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
|
|
│ │ │
|
|
│ │ └─⫸ Exclamation mark: breaking change
|
|
│ │
|
|
│ └─⫸ Commit Scope: bot|website
|
|
│
|
|
└─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test
|
|
```
|
|
|
|
The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is optional.
|
|
Exclamation mark is optional too, but it's used to mark breaking changes.
|
|
|
|
##### Type
|
|
|
|
Must be one of the following:
|
|
|
|
- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
|
|
- **ci**: Changes to our CI configuration files and scripts (examples: CircleCi, SauceLabs)
|
|
- **docs**: Documentation only changes
|
|
- **feat**: A new feature
|
|
- **fix**: A bug fix
|
|
- **perf**: A code change that improves performance
|
|
- **refactor**: A code change that neither fixes a bug nor adds a feature
|
|
- **test**: Adding missing tests or correcting existing tests
|
|
|
|
##### Scope
|
|
|
|
The scope should be the name of the npm package affected (as perceived by the person reading the changelog generated from commit messages).
|
|
|
|
The following is the list of supported scopes:
|
|
|
|
- `bot`
|
|
- `website`
|
|
|
|
There are currently a few exceptions to the "use package name" rule:
|
|
|
|
- none/empty string: useful for `test` and `refactor` changes that are done across all packages (e.g. `test: add missing unit tests`) and for docs changes that are not related to a specific package (e.g. `docs: fix typo in tutorial`).
|
|
|
|
##### Summary
|
|
|
|
Use the summary field to provide a succinct description of the change:
|
|
|
|
- use the imperative, present tense: "change" not "changed" nor "changes"
|
|
- don't capitalize the first letter
|
|
- no dot (.) at the end
|
|
|
|
#### <a name="commit-body"></a>Commit Message Body
|
|
|
|
Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
|
|
|
|
Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are making the change.
|
|
You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
|
|
|
|
#### <a name="commit-footer"></a>Commit Message Footer
|
|
|
|
The footer is optional and is used for two purposes:
|
|
|
|
- To reference issues that this commit closes
|
|
- To include information that doesn't fit in the header or body, such as a link to a file or a suggestion to review a pull request
|
|
|
|
The format for the footer is as follows:
|
|
|
|
```
|
|
Closes/Fixes #<issue number>
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
See pull request #<pull request number>
|
|
```
|
|
|
|
### Revert commits
|
|
|
|
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
|
|
|
|
The content of the commit message body should contain:
|
|
|
|
- information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`,
|
|
- a clear description of the reason for reverting the commit message.
|