DS-0001 Conventional Commits

Overview

Conventional Commits is a widely adpoted standard way of writing a commit message.

Before proceeding further, please peruse the full spec from the Conventional Commits offical website.

The short summary of a conventional commit message is:

<type>[(scope)][!]: <description>
<blank line>
[body]
<blank line>
[footer(s)]

Types

This DS-0001 standard recommends the use of the following types:

  • build: Changes that affect the build system or external dependencies
  • chore: A code change that is neither a feat or a fix (example: bumping versions of dependencies)
  • ci: Changes to CI configuration files and scripts
  • 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
  • revert: A commit that reverts a previous commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests
  • wip: Indicates this commit is a Work-In-Progress

Scopes

Every repo should have a list of scopes clearly defined in the repo’s README file. Commit message may use a scope to clarify what part of the codebase this commit touches. For multiple scopes, use a comma separation.

Breaking Change

If the commit introduces a breaking change, it must be indicated using an exclamation (!) after the type/scope and before the colon (:).

Description

The description is a short summary of the code changes. The description shall be written in imperative. The first line, including type, scope and description shall not exceed 50 characters. TIP: If you set your git config core.editor=vim, it will automatically highlight when you are going over 50 characters. Description shall start with a lower case.

Here are some correct and wrong examples for description:

✅ add foo to main menu

❌ adding foo to main menu

❌ added foo to main menu

A good way to think about writing in imperative, is to try to fill in the blank of the sentence:

If merged, this commit will _________________________.

What you write in the blank will usually be in imperative.

Body

A commit body is free-form and may consist of any number of newline separated paragraphs. Try to add more context about the commit focussing on WHY this change was introduced rather than WHAT code was changed. Most developers can see the commit diff and easily figure out the WHAT part - answering the WHY question adds value to the commit message. Remember, you yourself may be wondering about WHY did I make this change on your own commit a few months down the road.

One or more footers may be provided one blank line after the body. Each footer must consist of a word token, followed by a : separator, followed by a string value. The token must not have spaces, instead it must use - to separate words.

This is an non-exhaustive example list of possible footers:

BREAKING-CHANGE: This commit will break the code for database records in the old schema.

Closes: JIRA-123

Refer: JIRA-456

Reviewed-by: Bob bob@example.com

Signed-off-by: Alice alice@example.com

Why

Conventional commits standardize and make it easy to read commit messages. It also helps in writing tools to parse commit messages are automatically generate changelogs, or suggest semantic version number updates based on the presence of fix (patch version is incremented) or feat (minor version is incremented) etc. Tools can also parse the token: value syntax of the footers to process information contained therein.

References and Credits

This work, “DS-0001 Conventional Commits”, is adapted from “Conventional Commits” used under CC BY 3.0. “DS-0001 Conventional Commits” is licensed under CC BY-NC 4.0 by Dev Eh Inc.