--- title: "Commit Messages" description: "We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history." url: https://develop.sentry.dev/engineering-practices/commit-messages/ --- # Commit Messages ### [General Rules](https://develop.sentry.dev/engineering-practices/commit-messages.md#general-rules) 1. Separate subject from body with a blank line 2. Limit the subject line to 70 characters 3. Capitalize the subject line 4. Do not end the subject line with a period 5. Use the imperative mood in the subject line 6. Use the body to explain what and why vs. how 7. Each commit should be a single, stable change ### [Squash Merge](https://develop.sentry.dev/engineering-practices/commit-messages.md#squash-merge) Sentry enforces **squash-merge** for all pull requests into the default branch. This means that regardless of how many commits your feature branch has, they will be combined into a single commit when merged. The resulting commit message is what matters — it should follow the commit message format described below. Because of this, you do **not** need to keep your branch’s individual commits clean or rebased. Feel free to commit incrementally, use fixup commits, or have “WIP” messages during development — they will all be squashed away on merge. #### [Updating Your Branch](https://develop.sentry.dev/engineering-practices/commit-messages.md#updating-your-branch) When your branch is behind the default branch, we advise **merging** main into your branch over rebasing: * **Merge** preserves the existing commit history and, importantly, keeps the context of already-reviewed changes intact. Reviewers can see only the new changes since their last review. * **Rebase** rewrites your branch’s commit history, which makes every commit appear new to reviewers and loses the ability to see incremental changes. This is especially disruptive on PRs that have already received review feedback. #### [Squashing a Merge Commit Message](https://develop.sentry.dev/engineering-practices/commit-messages.md#squashing-a-merge-commit-message) When squash-merging via GitHub’s UI, consider taking this opportunity to craft a clear final commit message that follows the commit guidelines below. The default squash-merge message varies by repository — some use the PR title and description, while others concatenate all individual commit messages. ### [Commit Message Format](https://develop.sentry.dev/engineering-practices/commit-messages.md#commit-message-format) Each commit message consists of a **header**, a **body**, and an optional **footer**. The header has a special format that includes a type, a scope and a subject: ```bash (): ()