xsteadfastx/conventionalcommits.org
1
0
Fork 0
mirror of https://github.com/conventional-commits/conventionalcommits.org.git synced 2024-11-15 02:45:15 +01:00
Code Issues Projects Releases Wiki Activity

feat: reduce ambiguity around footer/body (#185)

Browse Source
This commit is contained in:
Benjamin E. Coe 2019-09-06 21:58:25 -04:00 committed by GitHub
parent 31c444cc2b
commit 0224669ebe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
content/next/index.md
View File

@ -21,7 +21,7 @@ The commit message should be structured as follows:
[optional body]
[optional footer]
[optional footer(s)]
```
---
@ -31,18 +31,19 @@ consumers of your library:
1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in semantic versioning).
1. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in semantic versioning).
1. **BREAKING CHANGE:** a commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning).
1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in semantic versioning).
A BREAKING CHANGE can be part of commits of any _type_.
1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
1. _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [the Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
1. _footers_ other than `BREAKING CHANGE: <description>` may be be provided and and follow a convention similar to
[git trailer format](https://git-scm.com/docs/git-interpret-trailers).
We also recommend `improvement` for commits that improve a current implementation without adding a new feature or fixing a bug.
Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
<br />
Additional types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE).
<br /><br />
A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.
## Examples
### Commit message with description and breaking change in body
### Commit message with description and breaking change footer
```
feat: allow provided config object to extend other configs
@ -54,11 +55,12 @@ BREAKING CHANGE: `extends` key in config file is now used for extending other co
chore!: drop Node 6 from testing matrix
```
### Commit message with both `!` and BREAKING CHANGE in body
### Commit message with both `!` and BREAKING CHANGE footer
```
chore!: drop Node 6 from testing matrix
BREAKING CHANGE: dropping Node 6 as it hits end of life in April
BREAKING CHANGE: dropping Node 6 as it hits end of
life in April
```
### Commit message with no body
@ -71,13 +73,16 @@ docs: correct spelling of CHANGELOG
feat(lang): add polish language
```
### Commit message for a fix using an (optional) issue number.
### Commit message with multi-paragraph body and multiple footers
```
fix: correct minor typos in code
see the issue for details on the typos fixed
see the issue for details
closes issue #12
on typos fixed.
Reviewed-by: Z
Refs: #133
```
## Specification
@ -85,25 +90,32 @@ closes issue #12
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
1. Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed
by an OPTIONAL scope, and a REQUIRED terminal colon and space.
by the OPTIONAL scope, OPTIONAL `!`, and REQUIRED terminal colon and space.
1. The type `feat` MUST be used when a commit adds a new feature to your application or library.
1. The type `fix` MUST be used when a commit represents a bug fix for your application.
1. A scope MAY be provided after a type. A scope MUST consist of a noun describing a
section of the codebase surrounded by parenthesis, e.g., `fix(parser):`
1. A description MUST immediately follow the space after the type/scope prefix.
1. A description MUST immediately follow the colon and space after the type/scope prefix.
The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string._
1. A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
1. A footer of one or more lines MAY be provided one blank line after the body. The footer MUST contain meta-information
about the commit, e.g., related pull-requests, reviewers, breaking changes, with one piece of meta-information
per-line.
1. Breaking changes MUST be indicated in the type/scope prefix of a commit, or at the beginning of its optional body or footer section.
1. If included in the body or footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g.,
1. A commit body is free-form and MAY consist of any number of newline separated paragraphs.
1. One or more footers MAY be provided one blank line after the body. Each footer MUST consist of
a word token, followed by either a `:<space>` or `<space>#` separator, followed by a string value (this is inspired by the
[git trailer convention](https://git-scm.com/docs/git-interpret-trailers)).
1. A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate
the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE`, which MAY also be used as a token.
1. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer
token/separator pair is observed.
1. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as a trailer
in the footer.
1. If included as a trailer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g.,
_BREAKING CHANGE: environment variables now take precedence over config files._
1. If included in the type/scope prefix, breaking changes MUST be indicated by a
`!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be ommitted from the
body or footer section, and the commit description SHALL be used to describe the breaking change.
1. Types other than `feat` and `fix` MAY be used in your commit messages.
`!` immediately before the `:`. If `!` is used, `BREAKING CHANGE:` MAY be ommitted from the footer section,
and the commit description SHALL be used to describe the breaking change.
1. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: updated ref docs._
1. The units of information that make up conventional commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
1. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.
## Why Use Conventional Commits