Skip to content
The Holocron

Commit Conventions

Commits should be small, concise and logical units of code. The goal is not to overwhelm reviewers with superfluous changes; do not add any unrelated changes to a commit in case the change needs to be reverted or backed out. The entirety of your code should answer the question:

Which problem am I trying to solve today?

All changes should be connected and without 1 change your entire commit would fall apart. If you find that you can keep a commit out and your code still makes sense, runs successfully, and fixes an issue then you’re likely in a good condition to commit some code and create a pull request. Contributors are required to follow the Conventional Commits specification on all commit messages. If you’re ready, follow below to create a good commit message in the proper format.

A few tips to consider:

  • Absolutely no working directly on the main branch!!!
  • Check for unnecessary blank space with git diff --check before committing.
  • And be sure to run git commit and NOT git commit -m <message> so that you can fill out the body of the message

Parts of a Commit

A commit should consist of a required title, optional but recommended body and an optional but recommended footer. Below is the desired format with an example:

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

Example

fix(filter): patch Autocomplete output when query is empty


Show default options when no Autocomplete search input value is present.


Fixes #1234

Title

  • The first line should be less than 50 characters (our git-hooks will warn about this) but no greater than 72.
  • The and should always be lowercase as shown in example.
  • is required
  • is optional
  • should be written in the imperative with present tense.
  • Should contain no full stop (.).

Allowed type values

  • feat (new feature for the user, not a new feature for build script)
  • fix (bug fix for the user, not a fix to a build script)
  • chore (updating tasks etc, changes to docs, linting warnings, adding tests; no production code change)

What is scope

should indicate the feature, component, or part that is being fixed. It should be very short but obvious.

The value can be omitted. The feature may not exist or be too complex to assign to a single component. If the is empty the parenthesis should not be added to the title.

Body

  • optional, thorough descriptions are helpful for understanding commits
  • wrap it to about 72 characters or so
  • uses the imperative, present tense: “change” not “changed” nor “changes”; this convention matches up with commit messages generated by commands like git merge and git revert
  • includes motivation for the change and contrasts with previous behavior
  • it’s more important that you include why these changes were made then listing out what was done
  • must be separated by a blank line from title
  • in some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
  • further paragraphs come after blank lines.
  • bullet points are okay, too
  • typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here
  • use a hanging indent
  • optional
  • can reference which task it covers
  • can cover breaking changes
  • must be separated by a blank line