Differences

This shows you the differences between two versions of the page.

--- software:git [2026/08/08 17:43] – created - external edit 127.0.0.1
+++ software:git [2026/08/20 13:34] (current) – ron
@@ Line 1: / Line 1: @@
-# Conventional Commit Messages
+====== Conventional Commits ======
+  * based on [[https://www.conventionalcommits.org/en/v1.0.0/#specification|this spec]]
+===== Structure =====
+<code>
+<type>[(<scope>)][!]: <description>
+[<body>]
+[<footer(s)>]
+</code>
+===== 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: <html><description></html> 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 :<html><space></html> or <html><space></html># 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.