Sentry commit message conventions

Contract

Format every git commit as <type>(<scope>): <Subject> with an optional body and footer, using Sentry's specific spellings and casing. Apply whenever you write or revise a commit message. These rules differ from plain Conventional Commits in three ways the base gets wrong: the type token ref (not refactor), a Capitalized subject (not lowercase), and the Refs/Fixes footer keywords.

Rules

1. Header structure

<type>(<scope>): <Subject>

• The header line is required. <scope> and the parentheses are optional.
• Exactly one space after the colon. No space before the colon.
• The whole header (type + scope + subject) is at most 70 characters.
• Every line in the message stays under 100 characters.

2. Type token — use the Sentry spellings

Pick exactly one type from this closed set. The spellings in bold are the ones that differ from the common Conventional-Commits vocabulary:

| Type | Use for | |------|---------| | feat | A new feature or user-visible capability | | fix | A bug fix | | ref | Refactoring with no behavior change (NOT refactor) | | perf | A performance improvement, no new behavior | | docs | Documentation only | | test | Adding or correcting tests | | build | Build system, dependencies, lockfiles, bundler config | | ci | CI configuration (e.g. GitHub Actions workflows) | | chore | Maintenance: dead-code removal, copyright bumps | | style | Formatting only — whitespace, quotes, no logic change | | meta | Repository metadata (CODEOWNERS, issue templates) | | license | License changes |

The type token is lowercase. There is no other valid type — do not invent improvement, update, misc, or wip.

3. Scope

• Optional. When present it goes in parentheses immediately after the type:

fix(api):.

• The scope is lowercase and is a short noun for the affected area (api,

alerts, auth). No spaces inside the parentheses.

4. Subject

• Capitalize the first letter of the subject: fix(api): Handle null response.

This is the opposite of lowercase Conventional Commits and the single most common base mistake.

• Imperative present tense: Add, Handle, Remove, Extract. Never past tense

(Added, Fixed) and never gerund (Adding, Fixing).

• No trailing period.
• Describe what the change does, concisely.

5. Body (optional)

• Separate from the header with one blank line.
• Explain what and why, not how. Include motivation; contrast with the previous

behavior when it clarifies the change.

• Imperative present tense, same as the subject. Wrap at <100 chars.

6. Footer — issue references

Put issue references in the footer, separated from the body by a blank line. The keyword choice is meaningful:

• Fixes — closes the issue when the commit merges. Use when the change resolves

the issue: Fixes SENTRY-1234, Fixes GH-1234, Fixes #1234.

• Refs — links the issue without closing it. Use the exact keyword Refs,

never See, Related, Ref, or References: Refs GH-1234, Refs LINEAR-ABC-123.

Issue identifier forms: #1234, GH-1234, SENTRY-1234, LINEAR-ABC-123.

7. Breaking changes

A breaking change needs both signals:

1. A ! immediately after the type or scope and before the colon: feat(api)!: or

feat!:.

1. A footer line beginning with BREAKING CHANGE: describing the break.

8. Revert

Format a revert as:

revert: <original header>

This reverts commit <full-sha>.

Reason: <why it was reverted>

The header is revert: followed verbatim by the reverted commit's original header.

Worked examples

Each example shows the base model's wrong default (BEFORE) and the conforming form (AFTER).

Rule 2 — ref, not refactor

Task: you moved duplicate validation out of three handlers into one shared class; no behavior change.

BEFORE (base default):

refactor: extract validation logic into a shared module

AFTER:

ref: Extract validation logic into a shared module

Move duplicate validation from three endpoints into one validator class.
No behavior change.

Rule 4 — Capitalize the subject

Task: handle a null response in the user endpoint.

BEFORE (lowercase Conventional Commits default):

fix(api): handle null response in user endpoint.

AFTER (capitalized first letter, no trailing period):

fix(api): Handle null response in user endpoint

Rule 4 — imperative present tense

Task: add CSV export to the reports page.

BEFORE (past/gerund tense):

feat: Added CSV export to reports page

AFTER:

feat: Add CSV export to the reports page

Rule 6 — Refs links without closing

Task: alerts now post Slack thread replies; link GH-1234 but do not close it.

BEFORE (base reaches for Closes/Fixes):

feat: add slack thread replies for alerts

Closes GH-1234

AFTER:

feat(alerts): Add Slack thread replies for alert updates

Post a reply to the original Slack thread instead of a new message, keeping
related notifications grouped.

Refs GH-1234

Rule 6 — Fixes closes the issue

Task: add a null check that resolves SENTRY-5678.

BEFORE:

fix: null check for deleted accounts (SENTRY-5678)

AFTER:

fix(api): Handle null response for deleted accounts

The user API returned null for deleted accounts and crashed the dashboard.
Add a null check before reading user properties.

Fixes SENTRY-5678

Rule 7 — breaking change needs ! AND footer

Task: remove the deprecated v1 endpoints; closes SENTRY-9999.

BEFORE (one signal only):

feat: Remove deprecated v1 endpoints

Fixes SENTRY-9999

AFTER:

feat(api)!: Remove deprecated v1 endpoints

Remove all v1 API endpoints deprecated in 23.1. Clients migrate to v2.

BREAKING CHANGE: v1 endpoints are no longer available
Fixes SENTRY-9999

Rule 8 — revert format

BEFORE:

Revert "Add new endpoint" — broke prod

AFTER:

revert: feat(api): Add new endpoint

This reverts commit abc123def456.

Reason: Caused a performance regression in production.

Edge cases & exceptions

• ref vs perf: if the change keeps behavior the same but improves speed, use

perf. If it restructures code with no perf or behavior change, use ref.

• build vs ci: dependency/lockfile/bundler changes are build; the CI pipeline

config (workflow YAML) is ci.

• chore vs style vs ref: pure formatting/whitespace is style; dead-code

removal and housekeeping is chore; reorganizing live code is ref.

• meta vs docs: repository metadata files (CODEOWNERS, issue templates) are

meta; human-readable documentation (README, guides) is docs.

• Both link and close: a commit may carry multiple footer lines — e.g. Fixes

one issue and Refs another. Each reference goes on its own line.

• Breaking change with no issue: still requires the ! and the BREAKING CHANGE:

footer; the issue footer is just absent.

• Scope when unsure: scope is optional — omit it rather than guessing a wrong area.

Do / Don't

• Never refactor: — always ref:.
• Never a lowercase subject — always capitalize the first letter.
• Never a trailing period on the subject — always end without punctuation.
• Never past/gerund tense (Added, Adding) — always imperative (Add).
• Never See / Related / Closes to link without closing — always Refs.
• Never rely on ! alone for a breaking change — always add the BREAKING CHANGE:

footer too.

• Never invent a type (update, improvement, wip) — always use a token from the

table.

Common mistakes

• Writing refactor (the universal Conventional-Commits token) instead of ref.
• Lowercasing the subject because most Conventional-Commits guides do.
• Adding a trailing period to the subject line.
• Using Closes/Resolves when the intent is to link (should be Refs), or See

when the intent is to close (should be Fixes).

• Marking a breaking change with only ! or only the BREAKING CHANGE: footer.
• Using refactor-flavored types like cleanup or improvement not in the set.

Quick checklist

• ] Type from the closed set, Sentry spelling (ref not refactor).
• ] Optional lowercase scope in parentheses.
• ] Subject capitalized, imperative present, no trailing period, header ≤70 chars.
• ] Body explains what/why (optional), lines <100 chars.
• ] Footer: Fixes to close, Refs to link.
• ] Breaking change → ! AND BREAKING CHANGE: footer.
• ] Revert → revert: + This reverts commit <sha>. + Reason:.