---
description: How commit messages should be structured.
title: Commit message guide
image: images/blockly_banner.png
---

# Commit message guide

## Commit messages

Clear commit messages make pull requests easier to review, and release notes
easier to generate. The Blockly project uses
[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to help
with this.

Each commit should have the format:

```none
<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:

```none
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.

### Footer

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](#commit-messages) 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits)
    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`.
