Edit on GitHub
English

The Symbol Handbook

Everything you need to know about the Symbol Syndicate.

Commit discipline

Proper commit message content and format.

Table of Contents

Summary

OK, so you’ve finished your work and you are naturally eager to git push it and start working on something else, new and exciting. I know the feeling, we have all been there.

Well, I have news for you: The truly excellent developer grits their teeth and walks the extra mile, spending the time to write a good commit message for all of posterity to see.

Just like a tree is harder to implement than a list, but provides orders of magnitude better runtime performance , writing good commit messages takes you more time, but saves time for everybody else reading your code in the future (including your future self).

There is a net gain for everybody here. Just consider what happens when you need to review somebody else ’s code and it has been tagged with proper git messages. Cool, isn’t it? A game-changer even?

We strive to be truly excellent developers here, so grit your teeth and spend the time to write a good commit message after every completed job. This guide explains you how to do it.

Proper commit messages are extremely important as they simplify maintainability :

NOTE : The following commit message format and content are mandatory , and will be enforced by server hooks in the future ( symbol-infra/issues/17 ).

Commit Message Content

This is the most important bit of this document:

A good commit message explains the reason behind the change , this is, the why of the commit.

What the commit does, and how it does it, is already shown in the actual commit. The good commit message includes the missing information, like:

Commit Message Format

Additionally, if the commit message adheres to a strict format, it can enable some interesting automation.

We have decided to follow the Conventional Commits specification:

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with  SemVer , by describing the features, fixes, and breaking changes made in commit messages.

The benefits are:

In summary, all commits must have this format: 

  <type>[optional scope]: <description> <body> [optional footer(s)]

Type

Valid types (based on the Angular convention ) are:

Type Meaning
build Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
ci Changes to the CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs).
docs Documentation only changes.
feat A new feature. This will change the MINOR version .
fix Patches a bug in the codebase. This will change the PATCH version .
perf A code change that improves performance.
refactor No functional changes, just moving code around for maintainability.
style Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, …).
test Adding missing tests or correcting existing ones.

The type can be followed by an exclamation mark ! indicating that this is an API BREAKING CHANGE (see the footer section below).

Scope

A scope may be provided after a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays .

One or more footers may be provided one blank line after the body. Each footer must consist of a word token, followed by either a  :<space>  or  <space>#  separator, followed by a string value (this is inspired by the  git trailer convention ).

BREAKING CHANGE is a special token that will change the MAJOR version . This can also be indicated with a ! after the type or scope.

Examples:

Description

It follows the colon and space after the type/scope prefix. The description is a single-line summary of the code changes, e.g.,  fix: array parsing issue when multiple spaces were contained in string .

Body

This goes into the <body> of the commit message and it should try to address all the points in the Commit Message Content section above.

The body can be omitted only when the commit is short , its description is self-explanatory and links to further information (like issue numbers, if any) are already given in the footer .

Skipping the body should be a rare case . A clear example could be fix: spelling errors , but coding typos must definitely have a body: Even though the fix might be simple, the commit message must explain at least what the ill effects were.

Examples