Skip to main content

Use Conventional Commit style for commit messages

  • Status: [Proposed]
  • Deciders: Web and Mobile Teams
  • Date: [3/11/2024, 5/13/2024]

Context​

Current commit messages are subjectively created and don't convey structured information that is easy to read, or usable by tooling. The OTU course on Abyss says conventional commits are used already, but it is not.

We think standardizing commit messages will improve the readability, maintainability, and automation potential of our commit history. Standardized commit messages enable these benefits, and are the process change this ADR addresses.

Decision​

We will use conventional commit messages as described below. We will implement enforcement of them, at least upon merge to main in a Github action (implementation described in US6770215). The preferred message tone will be imperative tense, and the lists of tasks and scopes, and presence of a ticket will not be enforced - only the format.

Example commit message in PR:

feat(web): add new name-tagging component [US987654]

In the history of the main branch, the merge of the Pull Request will then look like the following (since the PR number is appended by Github upon merge):

feat(web): add new name-tagging component [US987653] (#2499)
docs(mobile): update tokens docs [US987654] (#2500)

Prior Art​

The Conventional Commit format is the only widely-known format, and is used heavily by Angular and RxJS - two very popular libraries in the web space.

Specifics​

Prefer to use the tasks and scopes in this ADR, and to include a ticket number, but to avoid constant changes to the tooling, only the format, with optional ticket number, will be enforced.

Options​

The segments of a Conventional Commit (CC) message are the:

  • Task / Change Type
  • Scope
  • Message
  • Ticket ID

and is composed like this:

task(scope): message [ticketID]

Task / Change Type​

A task describes the type of change in the commit. Preferred tasks (from config-conventional) will be:

  • a11y, build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

A task is required. If a commit introduces breaking change, the combination of task and scope should be appended with !. Example:

refactor(web)!: rename onConvert handler to onChange

The following tasks are intended to increment the SemVer minor version:

  • feat

The following tasks are intended to increment the SemVer patch version only:

  • fix, perf, a11y, refactor, style

Scopes​

The following are the preferred scopes:

  • web, mobile, core, api, parcel, utility, design

A scope is highly recommended, and if omitted, implies the scope is the entire repository, which could over-trigger automations.

Message​

The CC format pre-allocates around 20 of the recommended 72-80 characters for a git commit title, leaving room for only a brief message of about 10 words/50 characters.

Your commit message should complete the sentence:

This commit is necessary in order to ...

  • Add a component
  • Update the tokens section reflecting new API
  • etc...

This is called writing in the imperative tense, and coincidentally reads like a prompt you'd give to an AI to create the commit.

If a commit contains a breaking change, the combination of task and scope should be appended with !, and the commit message after the title line should contain the words 'BREAKING CHANGE'.

Integrate AHA and/or RALLY reference in the ticket​

The RALLY ticket identifier at a minimum, and the AHA ticket identifier if appropriate, should be included at the end of the commit message. These should be in square brackets at the end, to remain flexible as to any ticket-numbering scheme.

feat(web): add new name-tagging component [US987654] [AHA-1001]

Feel free to use multiple lines for other references to other documents or task trackers, but the Rally ticket is expected to be the first field, on the title line.

Consequences​

Benefits​

  • Better readability of commit history.
  • Standard, objective detection of version updates and deployments.
  • AI tooling may be able to assist in creating these messages.

Costs​

  • Developers will have to learn and adjust to this process.
  • The merge of a PR might be rejected until its commit message is rewritten to conform, which could lengthen the merge process.
  • We'll have to maintain tooling to adapt to format changes or modifications to our conventions.

Future Considerations​

  • Implementation will be specified and delivered in US6770215.

Revision History​

  • 11/15/2024: added design to pr scope for token migration PR #3056
Table of Contents