Commit Message Guide

Stay organized with collections Save and categorize content based on your preferences.

Commit messages

Clear commit messages make pull requests easier to review, and release notes easier to generate. The Blockly project uses conventional commits to help with this.

Each commit should have the format:

<type>: <description>

[optional body]

[optional footer(s)]

Note that the core Blockly repo has a commit linter to help enforce this. If your pull request has multiple commits, the linter will check the title. If it has a single commit, it will check that commit. It is best if both your individual commits and the pull request title follow these guidelines.

Type

The type must be non-empty, and all lower case. The following is a list of accepted types.

chore
For commits that complete routine/automated tasks such as upgrading dependencies.
deprecate
For commits that deprecate functionality.
feat
For commits that add new functionality to Blockly.
fix
For commits that fix bugs/errors in Blockly.
release
For commits that relate to the release of a new version.

Breaking changes

Commits that make breaking changes should append a ! after the type of the commit. Breaking changes are changes that may break developers using Blockly in their apps, causing them to have to do extra work.

For example: fix!: return type of workspace.paste

Breaking changes could have any of the above valid types.

Description

The description must be non-empty, and must be under 256 characters.

Body

The body is optional. If it is provided there should be a blank line between it and the description. It must be broken into lines of no more than 256 characters.

Note that usually, it is advisable to put this kind of information in your pull request description, in addition to/rather than directly in the commit.

The footer is optional. If it is provided there should be a blank line between it and the body. It must be broken into lines of no more than 256 characters.

Fixing non-conventional commits

If you did not use conventional commits when making your modifications, there are two options for fixing the messages depending on how many commits you have:

  1. If your pull request has multiple commits, edit the pull request title to conform to the requirements. When the pull request is merged, your other commits will be squashed so that the title becomes the commit message.

  2. If your pull request has a single commit, amend your commit message using git commit --amend, then force push your changes to your fork of Blockly. This will automatically updated any open pull requests associated with this branch. git push --force origin my-branch.