Bitwise’s convention on how to structure, write, and use commit messages

Using a convention for commit messages has several benefits. For one, it makes it easier to find individual commits. It also forces us to keep our commits small enough to be able easily reason what they’re doing. And lastly to be able to revert small chunks of code if needed.

Git Commit Messages Conventions

There are many conventions available, many follow a close resemblance to the Conventional Commits specification.

👍 The one we use at Bitwise is based on the Karma Runner project. Please review it.

Guidelines:

• Each commit should contain files that all pertain to the same scope
• If you have changed multiple files that apply to different scopes, add and commit them separately
• Make your messages as direct and succinct as possible

Format

Your commit messages should be formatted as follows:

Short message example (git commit -m "..."):

type(scope):subject

Long message example (git commit):

type(scope):subject
(blank line)
body

type: Select one of the following 8 commit types. These are your only options for commit type:

• feat: A new feature for the application user. Rolling out a new module, new piece of functionality, etc.
• fix: Bug fix to your production code. Dealing with GH Issues, fixing a bug, etc.
• docs: Changes to your documentation. Adding a comment, editing a comment, changing README.md files, etc.
• style: Changes to your code formatting. This does not address CSS styling but rather the style of your code. Reformatting, adding semi-colons, etc.
• refactor: Refactor to production code. Upgrading a package and changing your code to meet the new demands, changing a let or a const name, etc.
• test: All things that apply to unit testing. Creating tests, refactoring tests, etc. No changes to production code occur.
• chore: Updating gulp, webpack, package.json files. This is developer-facing only.
• workaround: Temporary fix until a more robust solution is found or until other factors are resolved.

scope: Narrow the scope of the commit to a one or two word description in parentheses

subject: Favor imperative mood, present tense, active voice, and start with verbs. Don’t use a period at the end. Think of it as a newspaper headline.

body (optional): If necessary, provide additional context that can help other developers in the future. This is normally unnecessary but some use cases are:

• If the commit contains a new package you’ve added to the project
• If the commit contains a change to your build that you need to notate
• If the commit includes changes that would benefit from an explanation and from additional context.
• If the commit is the last in a series that will become a Pull Request and you want to communicate something to your senior developer.

Examples

Say you have changed four files:

app.component.ts app.router.ts login.component.ts login.component.scss

There are at least two scopes being dealt with here: the app.component scope and the login.component scope.

• git add the app.component.ts and the app.router.ts and create a commit for those files.

  git commit -m "refactor(app-component): import user service and add routes"

  Now you have 1 commit, dedicated to the app.component scope.

• Next, git add the login files and create a new commit message for these files.

  git commit -m "feat(login): create/setup" Note that this message is less verbose because it isnt necessary to add detail

Automation Tools 🛠

There are many tools available to help you enforce the commit convention rules via git hooks. This way you can always be sure that your commit will satisfy the rules before they’re added to the history.

One example, if you’re using npm/package.json in your project, you can install commitlint package. This adds a commit message linter to your command line. There are many plugins available for it with pre-configured convention rules, you can check them out here. If those don’t meet your needs you can extend them using a commitlint configuration file. You can then add the commitlint as a hook using Husky (directions here). After you set that up every time you try to run git commit it will first pass your commit message through the linter and either it will succeed or get rejected with a violation reason if it doesn’t comply with the rules.

If you find any other tools that you would like to share please open a PR.