Skip to content

Commit b20401b

Browse files
jstirnamanjstirnaman
committed
chore(qol): Add Claude command to enhance the release notes generated by generate-release-notes.js.claude/commands/enhance-release-notes.md file
 that provides Claude with detailed instructions for enhancing release notes. The command includes specific transformation patterns for different components (database, CLI, API, etc.) and provides fallback templates for handling edge cases. It also includes error handling for common issues like rate limits and private repositories.
1 parent 33a2d5c commit b20401b

File tree

2 files changed

+198
-0
lines changed

2 files changed

+198
-0
lines changed

‎.claude/commands/enhance-release-notes.md

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# enhance-release-notes
2+
3+
Analyze GitHub PRs referenced in release notes and enhance descriptions following Google Developer Documentation style.
4+
5+
## Overview
6+
7+
This command improves release note descriptions by:
8+
1. Fetching PR data from GitHub API
9+
2. Analyzing code changes and PR content
10+
3. Generating clear, action-oriented descriptions
11+
4. Following Google Developer Documentation principles
12+
5. Creating a descriptive commit message
13+
14+
## Usage
15+
16+
```
17+
enhance-release-notes <release-notes-file> [--dry-run]
18+
```
19+
20+
## Process
21+
22+
### 1. Extract PR References
23+
24+
- Scan the release notes file for GitHub PR links
25+
- Extract PR numbers and repository information
26+
- Example pattern: `([#26574](https://github.com/influxdata/influxdb/pull/26574))`
27+
28+
### 2. Fetch PR Data
29+
30+
For each PR, collect:
31+
- PR title and description
32+
- Files modified (to determine component scope)
33+
- Labels and metadata
34+
- Code change statistics
35+
36+
### 3. Analyze and Categorize
37+
38+
**Component Detection** (based on file paths):
39+
- `src/database/`, `catalog/`, `schema/` → Database operations
40+
- `cmd/`, `cli/` → CLI commands
41+
- `api/`, `http/` → HTTP API
42+
- `src/query/`, `sql/` → Query engine
43+
- `src/auth/`, `token/` → Authentication
44+
- `storage/`, `parquet/`, `wal/` → Storage engine
45+
- `license/` → License management
46+
47+
**Change Type Detection**:
48+
- `feat:` or "add", "new" → Feature
49+
- `fix:` or "resolve", "correct" → Bug fix
50+
- `perf:` or "optim", "faster" → Performance improvement
51+
52+
### 4. Generate Google Developer Documentation Style Descriptions
53+
54+
**Principles**:
55+
- Clear, concise, action-oriented language
56+
- Focus on what developers can do
57+
- Avoid marketing speak ("enhanced", "improved", "better")
58+
- Use specific, concrete benefits
59+
- Start with action verbs when possible
60+
61+
**Templates**:
62+
63+
**Database Operations**:
64+
- `hard.*delet.*date` → "Set custom hard deletion dates for deleted databases and tables"
65+
- `retention.*period` → "Configure automatic data expiration for databases"
66+
- `schema.*updat` → "Modify database schema after creation"
67+
68+
**CLI Commands**:
69+
- `help.*text` → "Access help documentation for commands"
70+
- `show.*license` → "View license details including expiration and limits"
71+
- `object.*store.*required` → "Specify object store configuration when starting the server"
72+
73+
**HTTP API**:
74+
- `v1.*query.*endpoint.*ns` → "Use nanosecond precision by default in V1 API CSV responses"
75+
- `trigger.*request_path` → "Configure processing engine triggers with request paths"
76+
77+
**Query Engine**:
78+
- `csv.*precision` → "Get consistent timestamp precision in CSV output"
79+
- `query.*performance` → "Execute queries without performance degradation"
80+
81+
**Authentication**:
82+
- `token.*creation` → "Generate tokens with additional configuration options"
83+
- `admin.*token.*expiration` → "Set expiration dates for admin tokens"
84+
85+
**Storage Engine**:
86+
- `aws.*credential.*reload` → "Automatically refresh AWS credentials from files"
87+
- `wal.*replay.*concurrency` → "Control memory usage during database startup"
88+
- `corrupt.*wal.*recovery` → "Recover from corrupted write-ahead log files"
89+
90+
**Fallback Patterns**:
91+
- Features: "Use [functionality] to [specific action]"
92+
- Bug fixes: "Avoid [specific problem] when [specific action]"
93+
- Performance: "Execute [operation] without [specific issue]"
94+
95+
### 5. Enhancement Format
96+
97+
Transform:
98+
```markdown
99+
- **Database management**: Allow hard_deleted date of deleted schema to be updated ([#26574](https://github.com/influxdata/influxdb/pull/26574))
100+
```
101+
102+
Into:
103+
```markdown
104+
- **Database operations**: Set custom hard deletion dates for deleted databases and tables ([#26574](https://github.com/influxdata/influxdb/pull/26574))
105+
```
106+
107+
### 6. Output Processing
108+
109+
**Dry Run Mode**:
110+
- Show before/after comparison
111+
- List all proposed changes
112+
- Don't modify the file
113+
114+
**Apply Mode**:
115+
- Replace descriptions in the original file
116+
- Preserve all formatting and PR links
117+
- Log successful enhancements
118+
119+
### 7. Create Descriptive Commit Message
120+
121+
After enhancing the release notes, generate a commit message:
122+
123+
**Format**:
124+
```
125+
docs: enhance release notes with specific user benefits
126+
127+
- Transform generic descriptions into action-oriented language
128+
- Add specific benefits following Google Developer Documentation style
129+
- Focus on what developers can do with each change
130+
- Enhanced [X] descriptions across [Y] components
131+
132+
Enhanced components: [list of components modified]
133+
```
134+
135+
**Example**:
136+
```
137+
docs: enhance v3.2.1 release notes with specific user benefits
138+
139+
- Transform generic descriptions into action-oriented language
140+
- Add specific benefits following Google Developer Documentation style
141+
- Focus on what developers can do with each change
142+
- Enhanced 8 descriptions across database, CLI, and API components
143+
144+
Enhanced components: Database operations, CLI commands, HTTP API
145+
```
146+
147+
## Error Handling
148+
149+
- **Missing GitHub token**: Warn about rate limits, continue with public API
150+
- **Private repos**: Skip PRs that can't be accessed
151+
- **Invalid PR URLs**: Log error and skip enhancement
152+
- **API rate limits**: Implement exponential backoff
153+
- **Network issues**: Retry with fallback to original description
154+
155+
## Configuration
156+
157+
**Environment Variables**:
158+
- `GITHUB_TOKEN`: Personal access token for GitHub API access
159+
160+
**GitHub Enterprise Support**:
161+
- Detect GitHub Enterprise URLs in PR links
162+
- Use appropriate API base URL
163+
164+
## Implementation Notes
165+
166+
1. **Rate Limiting**: Respect GitHub API rate limits (5000/hour authenticated, 60/hour unauthenticated)
167+
2. **Caching**: Consider caching PR data to avoid repeated API calls during development
168+
3. **Validation**: Verify PR URLs match expected format before API calls
169+
4. **Preservation**: Maintain all existing formatting, spacing, and non-PR content
170+
5. **Atomic Updates**: Only modify the file if all enhancements succeed (or provide partial success options)
171+
172+
## Example Usage
173+
174+
```bash
175+
# Dry run to see proposed changes
176+
enhance-release-notes release-notes-v3.2.1.md --dry-run
177+
178+
# Apply enhancements
179+
enhance-release-notes release-notes-v3.2.1.md
180+
181+
# With verbose output
182+
enhance-release-notes release-notes-v3.2.1.md --verbose
183+
```
184+
185+
## Success Criteria
186+
187+
1. All PR descriptions follow Google Developer Documentation style
188+
2. Descriptions focus on specific developer actions and benefits
189+
3. No marketing language or vague improvements
190+
4. Component categories are accurate based on code changes
191+
5. Original formatting and PR links are preserved
192+
6. Commit message clearly describes the enhancement approach

‎.github/copilot-instructions.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,12 @@ Help document InfluxData products by creating clear, accurate technical content
7373
- **Repository**: https://github.com/influxdata/docs-v2
7474
- **Framework**: Hugo static site generator
7575

76+
## Abbreviations and shortcuts
77+
78+
- `gdd`: Google Developer Documentation style
79+
- `3core`: InfluxDB 3 Core
80+
- `3ent`: InfluxDB 3 Enterprise
81+
7682
## Style guidelines
7783

7884
- Follow Google Developer Documentation style guidelines

0 commit comments

Comments
 (0)