====== Conventional Commits ======
* based on [[https://www.conventionalcommits.org/en/v1.0.0/#specification|this spec]]
===== Structure =====
[()][!]:
[]
[]
===== Types =====
* ''%%fix%%'' patches a bug in your codebase (this correlates with [[http://semver.org/#summary|PATCH]] in Semantic Versioning).
* ''%%feat%%'' introduces a new feature to the codebase (this correlates with [[http://semver.org/#summary|MINOR]] in Semantic Versioning).
* ''%%build%%'' fixes/changes the build process
* ''%%chore%%'' misc tasks; typically cleanup
* ''%%ci%%'' constant integration changes?
* ''%%docs%%'' changes to documentation
* ''%%style%%'' changes to code style
* ''%%refactor%%'' changes the implementation of a feature without changing any observable side-effects (including bugs)
* ''%%perf%%'' improves the performance of a feature
* ''%%test%%'' changes tests or the testing framework
* ''%%revert%%'' reverts previous commits; include reverted commit SHA-1 values
* [[https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional|@commitlint/config-conventional]]
* based on the [[https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines|Angular convention]]
===== Scope =====
* 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.
===== Footers =====
* BREAKING CHANGE: a commit that has a footer ''%%BREAKING CHANGE:%%'', or appends a ''%%!%%'' after the ''%%type/scope%%'', introduces a breaking API change (correlating with [[http://semver.org/#summary|MAJOR]] in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
* footers other than BREAKING CHANGE: may be provided and follow a convention similar to [[https://git-scm.com/docs/git-interpret-trailers|git trailer format]].
===== Full Spec =====
* Commits MUST be prefixed with a type, which consists of a noun, ''%%feat%%'', ''%%fix%%'', etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
* The type ''%%feat%%'' MUST be used when a commit adds a new feature to your application or library.
* The type ''%%fix%%'' MUST be used when a commit represents a bug fix for your application.
* 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):%%''
* 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%%''.
* 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.
* A commit body is free-form and MAY consist of any number of newline separated paragraphs.
* 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 : or # separator, followed by a string value (this is inspired by the [[https://git-scm.com/docs/git-interpret-trailers|git trailer convention]]).
* 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.
* A footer’s value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed.
* Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer.
* If included as a footer, 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%%''.
* If included in the type/scope prefix, breaking changes MUST be indicated by a ! immediately before the :.
* If ''%%!%%'' is used, BREAKING CHANGE: MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change.
* Types other than feat and fix MAY be used in your commit messages, e.g., docs: update ref docs.
* The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementers, with the exception of BREAKING CHANGE which MUST be uppercase.
* ''%%BREAKING-CHANGE%%'' MUST be synonymous with ''%%BREAKING CHANGE%%'', when used as a token in a footer.