CockroachDB Commit Helper
Help the user create properly formatted commit messages and release notes that follow CockroachDB conventions.
Workflow
- Analyze the changes: Run
git diff --staged or git diff to understand what was modified
- Determine the package prefix: Identify the primary package affected
- Ask the user for:
- Issue/epic number if not already known
- Whether release notes are needed and what category fits best
- Write the subject line: Imperative mood, no period, under 72 characters
- Write the body: Explain the before/after, why the change was needed
- Add issue references: Include Resolves/Epic as appropriate
- Write the release note: Clear, user-focused description of the change
- Create the commit using the properly formatted message
Commit Message Structure
Basic Format:
package: imperative title without period
Detailed explanation of what changed, why it changed, and
how it impacts users. Explain the problem that existed
before and how this commit solves it.
Include context about alternate approaches considered and
any side effects or consequences.
Resolves: #123
Epic: CRDB-357
Release note (category): Description of user-facing change
in past or present tense explaining what changed, how users
can see the change, and why it's important.
Key Requirements:
- Must include release note annotation (even if "Release note: None")
- Must include issue or epic reference
- Must separate subject from body with blank line
- Recommended prefix subject with affected package/area
- Recommended use imperative mood in subject (e.g. "fix bug" not "fixes bug")
- Recommended wrap body at 72-100 characters
Release Note Categories
When to include release notes:
- Changes to user interaction or experience
- Changes to product behavior (performance, command responses, architecture)
- Bug fixes affecting external users
When to exclude release notes:
- Internal refactors, testing, infrastructure work
- Code that's too immature for docs (private preview features)
- Internal settings beginning with
crdb_internal.
- Functionality not accessible to external users
Valid Categories:
backward-incompatible change - Breaking changes to stable interfacesenterprise change - Features requiring enterprise licenseops change - Commands/endpoints for operators (logging, metrics, CLI flags)cli change - Commands for developers/contributors (SQL shells, debug tools)sql change - SQL statements, functions, system catalogsui change - DB Console changessecurity update - Security feature changesperformance improvement - Performance enhancementscluster virtualization - Multi-tenancy infrastructurebug fix - Problem fixesgeneral change - Changes that don't fit elsewherebuild change - Source build requirements
Release Note Best Practices
Description guidelines:
- Default to more information rather than less
- Explain what changed, how it changed, and why it's relevant
- Use past tense ("Added", "Fixed") or present tense ("CockroachDB now supports")
- For bug fixes: describe cause, symptoms, and affected versions
- Note if change is part of broader roadmap feature
Examples:
Good bug fix:
Release note (bug fix): Fixed a bug introduced in v19.2.3 that
caused duplicate rows in CREATE TABLE ... AS results when multiple
nodes attempt to populate the results.
Good feature:
Release note (enterprise change): Shortened the default interval
for the kv.closed_timestamp.target_duration cluster setting from
30s to 3s. This allows follower reads at 4.8 seconds in the past,
a much shorter window than the previous 48 seconds.
Issue References
Resolves: #123 - Auto-closes issue on PR mergeSee also: #456, #789 - Cross-references issuesEpic: CRDB-357 - Links to epic
How to Avoid Common Pitfalls
- Always include a release note annotation (even "Release note: None")
- Use only valid category names from the list above
- Keep release notes focused on user-facing information
- Write specific descriptions that explain the impact to users
- Use
backward-incompatible change category for any breaking changes
- End subject lines without punctuation
- Explain the "why" behind changes, not just the "what"
Pull Request Guidelines
- Create PRs from your personal fork, not directly on cockroachdb/cockroach
- Single-commit PRs: PR title should match commit title, PR body should match commit body
- Multi-commit PRs: The body should summarize the end goal that the set of commits achieves and give the reader the context necessary to review the PR commit by commit (for example, the first commits might get refactors out of the way so that the last commit can hook everything up). When there isn't an overarching connection between the commits (maybe the PR groups a few mechanical changes that are not related) it is fine to say that the individual commits speak for themselves.
1---2name: commit-helper3description: Help create git commits and PRs with properly formatted messages and release notes following CockroachDB conventions. Use when committing changes or creating pull requests.4---5
6# CockroachDB Commit Helper
7
8Help the user create properly formatted commit messages and release notes that follow CockroachDB conventions.
9
10## Workflow
11
121. **Analyze the changes**: Run `git diff --staged` or `git diff` to understand what was modified
132. **Determine the package prefix**: Identify the primary package affected
143. **Ask the user** for:
15 - Issue/epic number if not already known
16 - Whether release notes are needed and what category fits best
174. **Write the subject line**: Imperative mood, no period, under 72 characters
185. **Write the body**: Explain the before/after, why the change was needed
196. **Add issue references**: Include Resolves/Epic as appropriate
207. **Write the release note**: Clear, user-focused description of the change
218. **Create the commit** using the properly formatted message
22
23## Commit Message Structure
24
25**Basic Format:**
26```
27package: imperative title without period
28
29Detailed explanation of what changed, why it changed, and
30how it impacts users. Explain the problem that existed
31before and how this commit solves it.
32
33Include context about alternate approaches considered and
34any side effects or consequences.
35
36Resolves: #123
37Epic: CRDB-357
38
39Release note (category): Description of user-facing change
40in past or present tense explaining what changed, how users
41can see the change, and why it's important.
42```
43
44**Key Requirements:**
45- **Must** include release note annotation (even if "Release note: None")
46- **Must** include issue or epic reference
47- **Must** separate subject from body with blank line
48- **Recommended** prefix subject with affected package/area
49- **Recommended** use imperative mood in subject (e.g. "fix bug" not "fixes bug")
50- **Recommended** wrap body at 72-100 characters
51
52## Release Note Categories
53
54**When to include release notes:**
55- Changes to user interaction or experience
56- Changes to product behavior (performance, command responses, architecture)
57- Bug fixes affecting external users
58
59**When to exclude release notes:**
60- Internal refactors, testing, infrastructure work
61- Code that's too immature for docs (private preview features)
62- Internal settings beginning with `crdb_internal.`
63- Functionality not accessible to external users
64
65**Valid Categories:**
66- `backward-incompatible change` - Breaking changes to stable interfaces
67- `enterprise change` - Features requiring enterprise license
68- `ops change` - Commands/endpoints for operators (logging, metrics, CLI flags)
69- `cli change` - Commands for developers/contributors (SQL shells, debug tools)
70- `sql change` - SQL statements, functions, system catalogs
71- `ui change` - DB Console changes
72- `security update` - Security feature changes
73- `performance improvement` - Performance enhancements
74- `cluster virtualization` - Multi-tenancy infrastructure
75- `bug fix` - Problem fixes
76- `general change` - Changes that don't fit elsewhere
77- `build change` - Source build requirements
78
79## Release Note Best Practices
80
81**Description guidelines:**
82- Default to more information rather than less
83- Explain **what** changed, **how** it changed, and **why** it's relevant
84- Use past tense ("Added", "Fixed") or present tense ("CockroachDB now supports")
85- For bug fixes: describe cause, symptoms, and affected versions
86- Note if change is part of broader roadmap feature
87
88**Examples:**
89
90**Good bug fix:**
91```
92Release note (bug fix): Fixed a bug introduced in v19.2.3 that
93caused duplicate rows in CREATE TABLE ... AS results when multiple
94nodes attempt to populate the results.
95```
96
97**Good feature:**
98```
99Release note (enterprise change): Shortened the default interval
100for the kv.closed_timestamp.target_duration cluster setting from
10130s to 3s. This allows follower reads at 4.8 seconds in the past,
102a much shorter window than the previous 48 seconds.
103```
104
105## Issue References
106- `Resolves: #123` - Auto-closes issue on PR merge
107- `See also: #456, #789` - Cross-references issues
108- `Epic: CRDB-357` - Links to epic
109
110## How to Avoid Common Pitfalls
111- Always include a release note annotation (even "Release note: None")
112- Use only valid category names from the list above
113- Keep release notes focused on user-facing information
114- Write specific descriptions that explain the impact to users
115- Use `backward-incompatible change` category for any breaking changes
116- End subject lines without punctuation
117- Explain the "why" behind changes, not just the "what"
118
119## Pull Request Guidelines
120- **Create PRs from your personal fork**, not directly on cockroachdb/cockroach
121- **Single-commit PRs**: PR title should match commit title, PR body should match commit body
122- **Multi-commit PRs**: The body should summarize the end goal that the set of commits achieves and give the reader the context necessary to review the PR commit by commit (for example, the first commits might get refactors out of the way so that the last commit can hook everything up). When there isn't an overarching connection between the commits (maybe the PR groups a few mechanical changes that are not related) it is fine to say that the individual commits speak for themselves.
cockroachdb