Skip to content

ADR: Git Commit Guidelines

Status

Approved (November 2023)

Context

Effective collaboration and version control are crucial aspects of software development. Git enables teams to work together efficiently and maintain a clear history of changes. Proper commit messages are essential for understanding the history of a project, tracking the context in which a change was performed and its intention and ease pull request reviews. This document outlines the guidelines for creating meaningful and informative Git commits.

We previously had no commit guidelines and no structure.

Decision

Atomicity

A commit:

  • MUST result in a usable app version. If checking out a commit would result in an unusable app, this commit should include the changes needed to stabilise the app, even if they need to be changed or removed in the next commits
  • MUST NOT mix white-space changes with functional code changes. Create 2 commits, white-space changes usually go first. Also, SHOULD separate multiple white-space changes on multiple commits
  • SHOULD represent a single logical change, not a user feature. If a change is too large, consider breaking it into smaller, atomic commits

Structure

A Git commit message MUST follow this structure:

<type><scope>: <subject>

<body>

<footer>

Type

Describes the purpose of the commit. MUST be one of the following conventional commit types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (e.g., formatting)
  • refactor: Code changes that neither fix a bug nor add a feature
  • perf: Performance improvements
  • test: Adding or modifying tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to the continuous integration pipeline
  • chore: Regular maintenance, refactoring, or updating build tasks
  • revert: Reverting a previous commit

MAY include an exclamation mark to point at breaking changes (in footer)

Scope

Describes the module or component affected by the commit:

  • MUST be surrounded by parenthesis
  • No standards, use your judgement. If you were to search this comment in the future, in which scope would you like to find it in?

Subject

A brief summary of the change:

  • MUST use the imperative mood: "Fix bug" and not "Fixed bug" or "Fixes bug"
  • MUST capitalise
  • MUST NOT end with a period
  • SHOULD always be able to complete the following sentence: "If applied, this commit will <subject>"
  • SHOULD be 72 chars or less

Body

Explain why you have done something:

  • MUST leave a blank line between subject and body
  • MUST describe why a change is being made and provide context
  • MUST capitalise each body paragraph
  • How does it address the issue?
  • What effects does the commit have?
  • Do not assume the reviewer understands what the original problem was
  • Do not assume the code is self-evident/self-documenting. In most cases, you can leave out details about how a change has been made
  • Describe any limitations of the current code
  • Read the commit message to see if it hints at mixed changes in commit (split if necessary)
  • Do not include patch set-specific comments. If you rebase your change, don't add "Patch set 2: rebased"

Provide additional issue references about the code changes:

  • MUST leave a blank line between body and footer
  • SHOULD contain information on scope breaking changes (if applicable) by including keyword BREAKING CHANGE and a description
  • SHOULD contain a link to the method grid element that this commit is related to (if applicable)

Examples

Commit message with description 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 with ! to draw attention to breaking change:

feat!: send an email to the customer when a product is shipped

Commit message with scope and ! to draw attention to breaking change:

feat(api)!: send an email to the customer when a product is shipped

Commit message with both ! and BREAKING CHANGE footer:

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Commit message with no body:

docs: correct spelling of CHANGELOG

Commit message with scope:

feat(lang): add Polish language

Consequences

By following these guidelines, we contribute to a clean version history that is easy to understand and navigate, benefiting both current developers and future contributors.

Impact

Medium

Driver

@Eudald Rossell Vivo

Contributors

[Team]

Accepted Date

November 2023

Resources

Last modified by: Unknown