Skip to content

Commit 34c8170

Browse files
bpmctclaude
bpmct
and
claude
committed
docs: add PR description style guide for agents
Adds a style guide documenting PR description patterns observed in the Coder repository. This guide is intended for AI agents to reference when creating PRs, ensuring consistency with project conventions. The guide covers title format (Conventional Commits), description structure (default concise vs. complex structured), what to include (links, performance context, warnings), and what to avoid (test plans, benefits sections). Includes examples from recent merged PRs demonstrating each pattern. Placed in .claude/docs/ alongside other agent-specific documentation (WORKFLOWS.md, ARCHITECTURE.md, etc.) rather than in the main contributing docs, as this is primarily for automated tooling reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 82bb833 commit 34c8170

File tree

1 file changed

+217
-0
lines changed

1 file changed

+217
-0
lines changed

‎.claude/docs/PR_STYLE_GUIDE.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Pull Request Description Style Guide
2+
3+
This guide documents the PR description style used in the Coder repository, based on analysis of recent merged PRs. This is specifically for PR descriptions - see [CONTRIBUTING.md](../../docs/about/contributing/CONTRIBUTING.md) for general PR guidelines (size limits, review process, etc.).
4+
5+
## PR Title Format
6+
7+
Follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) format:
8+
9+
```
10+
type(scope): brief description
11+
```
12+
13+
**Common types:**
14+
- `feat`: New features
15+
- `fix`: Bug fixes
16+
- `refactor`: Code refactoring without behavior change
17+
- `perf`: Performance improvements
18+
- `docs`: Documentation changes
19+
- `chore`: Dependency updates, tooling changes
20+
21+
**Examples:**
22+
- `feat: add tracing to aibridge`
23+
- `fix: move contexts to appropriate locations`
24+
- `perf(coderd/database): add index on workspace_app_statuses.app_id`
25+
- `docs: fix swagger tags for license endpoints`
26+
- `refactor(site): remove redundant client-side sorting of app statuses`
27+
28+
## PR Description Structure
29+
30+
### Default Pattern: Keep It Concise
31+
32+
Most PRs use a simple 1-2 paragraph format:
33+
34+
```markdown
35+
[Brief statement of what changed]
36+
37+
[One sentence explaining technical details or context if needed]
38+
```
39+
40+
**Example from PR #21100:**
41+
```markdown
42+
Previously, when a devcontainer config file was modified, the dirty
43+
status was updated internally but not broadcast to websocket listeners.
44+
45+
Add `broadcastUpdatesLocked()` call in `markDevcontainerDirty` to notify
46+
websocket listeners immediately when a config file changes.
47+
```
48+
49+
**Example from PR #21085:**
50+
```markdown
51+
Changes from https://github.com/coder/aibridge/pull/71/
52+
```
53+
54+
**Example from PR #21077:**
55+
```markdown
56+
Removes references to adding database replicas from the scaling docs,
57+
as Coder only allows a single connection URL. These passages where added in error.
58+
```
59+
60+
### For Complex Changes: Use "Summary", "Problem", "Fix"
61+
62+
Only use structured sections when the change requires significant explanation:
63+
64+
```markdown
65+
## Summary
66+
Brief overview of the change
67+
68+
## Problem
69+
Detailed explanation of the issue being addressed
70+
71+
## Fix
72+
How the solution works
73+
```
74+
75+
**Example from PR #21101:**
76+
```markdown
77+
## Summary
78+
Change `@Tags` from `Organizations` to `Enterprise` for POST /licenses...
79+
80+
## Problem
81+
The license API endpoints were inconsistently tagged...
82+
83+
## Fix
84+
Simply updated the `@Tags` annotation from `Organizations` to `Enterprise`...
85+
```
86+
87+
### For Large Refactors: Lead with Context
88+
89+
When rewriting significant documentation or code, start with the problems being fixed:
90+
91+
```markdown
92+
This PR rewrites [component] for [reason].
93+
94+
The previous [component] had [specific issues]: [details].
95+
96+
[What changed]: [specific improvements made].
97+
98+
[Additional changes]: [context].
99+
100+
Refs #[issue-number]
101+
```
102+
103+
**Example from PR #21080** (dev containers docs rewrite):
104+
- Started with "This PR rewrites the dev containers documentation for GA readiness"
105+
- Listed specific inaccuracies being fixed
106+
- Explained organizational changes
107+
- Referenced related issue
108+
109+
## What to Include
110+
111+
### Always Include
112+
113+
1. **Link Related Work**
114+
- `Closes https://github.com/coder/internal/issues/XXX`
115+
- `Depends on #XXX`
116+
- `Fixes: https://github.com/coder/aibridge/issues/XX`
117+
- `Refs #XXX` (for general reference)
118+
119+
2. **Performance Context** (when relevant)
120+
```markdown
121+
Each query took ~30ms on average with 80 requests/second to the cluster,
122+
resulting in ~5.2 query-seconds every second.
123+
```
124+
125+
3. **Migration Warnings** (when relevant)
126+
```markdown
127+
**NOTE**: This migration creates an index on `workspace_app_statuses`.
128+
For deployments with heavy task usage, this may take a moment to complete.
129+
```
130+
131+
4. **Visual Evidence** (for UI changes)
132+
```markdown
133+
<img width="1281" height="425" alt="image" src="..." />
134+
```
135+
136+
### Never Include
137+
138+
- ❌ **Test plans** - Testing is handled through code review and CI
139+
- ❌ **"Benefits" sections** - Benefits should be clear from the description
140+
- ❌ **Implementation details** - Keep it high-level
141+
- ❌ **Marketing language** - Stay technical and factual
142+
- ❌ **Bullet lists of features** (unless it's a large refactor that needs enumeration)
143+
144+
## Special Patterns
145+
146+
### Simple Chore PRs
147+
148+
For straightforward updates (dependency bumps, minor fixes):
149+
150+
```markdown
151+
Changes from [link to upstream PR/issue]
152+
```
153+
154+
Or:
155+
156+
```markdown
157+
Reference:
158+
[link explaining why this change is needed]
159+
```
160+
161+
### Bug Fixes
162+
163+
Start with the problem, then explain the fix:
164+
165+
```markdown
166+
[What was broken and why it matters]
167+
168+
[What you changed to fix it]
169+
```
170+
171+
### Dependency Updates
172+
173+
Dependabot PRs are auto-generated - don't try to match their verbose style for manual updates. Instead use:
174+
175+
```markdown
176+
Changes from https://github.com/upstream/repo/pull/XXX/
177+
```
178+
179+
## Attribution Footer
180+
181+
For AI-generated PRs, end with:
182+
183+
```markdown
184+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
185+
186+
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
187+
```
188+
189+
## Key Principles
190+
191+
1. **Be concise** - Default to 1-2 paragraphs unless complexity demands more
192+
2. **Be technical** - Explain what and why, not detailed how
193+
3. **Link everything** - Issues, PRs, upstream changes, Notion docs
194+
4. **Show impact** - Metrics for performance, screenshots for UI, warnings for migrations
195+
5. **No test plans** - Code review and CI handle testing
196+
6. **No benefits sections** - Benefits should be obvious from the technical description
197+
198+
## Examples by Category
199+
200+
### Performance Improvements
201+
See PR #21099 - includes query timing metrics and explains the index solution
202+
203+
### Bug Fixes
204+
See PR #21100 - describes broken behavior then the fix in two sentences
205+
206+
### Documentation
207+
See PR #21080 - long form explaining inaccuracies and improvements for major rewrite
208+
See PR #21077 - one sentence for simple correction
209+
210+
### Features
211+
See PR #21106 - simple statement of what was added and dependencies
212+
213+
### Refactoring
214+
See PR #21102 - explains why client-side sorting is now redundant
215+
216+
### Configuration
217+
See PR #21083 - adds guidelines with issue reference

0 commit comments

Comments
 (0)