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