Skip to content

Commit message guidelines

Jump to bottom
nivekyee edited this page Apr 24, 2021 · 3 revisions

Structure

Specification: https://www.conventionalcommits.org/en/v1.0.0/#specification

The commit message should be structured as follows:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Examples are provided at the end of this document.

Header

<type>[optional scope]: <subject>

  • The header should be limited to 50 characters but must be less than 72 characters

Type (required)

  • Commits must be prefixed with a type
  • A type must be one of the following:
    • feat: A new feature.
    • fix: A bug fix.
    • docs: Documentation only changes.
    • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
    • refactor: A code change that neither fixes a bug nor adds a feature.
    • perf: A code change that improves performance.
    • test: Adding missing tests.
    • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation.
  • If a scope is not provided, a ! after the type, indicates a breaking API change
  • If a scope is not provided, the type must have a terminal colon and space : before the subject

Scope (optional)

  • 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 ! after the scope, indicates a breaking API change
  • The scope must have a terminal colon and space : before the subject

Subject (required)

  • A subject must immediately follow the colon and space after the type/scope prefix
  • The subject is a short summary of the code changes
    • e.g., fix: array parsing issue when multiple spaces were contained in string.
  • The subject should be written in imperative form
    • e.g., change not changed, changes, or changing
  • The subject should not end with a period .

Body (optional)

  • A longer commit body may be provided after the short subject, providing additional contextual information about the code changes
  • The body must begin one blank line after the subject
  • A commit body is free-form and may consist of any number of newline separated paragraphs
  • The body should be written in imperative form

Footers (optional)

  • One or more footers may be provided one blank line after the body

Word Token (required)

  • Each footer must consist of a word token
  • 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 token must be followed by either a :<space> or <space># separator and then followed by a string value
    • e.g., Resolves #123, or Acked-by: David

String Value (required)

  • A footer’s value may contain spaces and newlines
  • Parsing must terminate when the next valid footer token/separator pair is observed

Break Changes

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 subject
    • 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 subject shall be used to describe the breaking change

Reverts

One recommendation is to use the revert type, and a footer that references the commit SHAs that are being reverted:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Examples

Commit message with scope

feat(lang): add polish language

Commit message with no body

docs: correct spelling of CHANGELOG

Commit message with ! to draw attention to breaking change

refactor!: drop support for Node 6

Commit message with subject and breaking change footer

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Commit message that closes multiple issues

fix: add connection from frontend to backend

Closes #234, #235

Group 39 Cream Cat - Andy Huang, Sunho Jung, Wenxin Pan, Kevin Yee

2021 Semester 1, CompSci 732 / SoftEng 750 - University of Auckland

Clone this wiki locally