Skip to content

Commit d08fcfd

Browse files
dlvenabledlvenable
authored
Adds prompts for creating Data Prepper release notes using AI tools. This allows us to use AI to create the release notes consistently between versions and across different maintainers. They are geared toward Claude but should work for tools like Kiro. (opensearch-project#6732)
Signed-off-by: David Venable <dlv@amazon.com>
1 parent 4ed2de8 commit d08fcfd

4 files changed

Lines changed: 248 additions & 3 deletions

File tree

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

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
Generate release notes for Data Prepper version $ARGUMENTS.
2+
3+
## Overview
4+
5+
You are generating user-facing release notes for the OpenSearch Data Prepper project.
6+
The milestone to use is: $ARGUMENTS
7+
8+
You will gather data from GitHub, categorize each item, reword it for clarity, and produce
9+
a release notes file following the project's established format.
10+
11+
## Step 1: Gather Data
12+
13+
Run these commands to fetch all closed issues and PRs for the milestone.
14+
Request the fields: number, url, title, labels, body.
15+
16+
```
17+
gh issue list --repo opensearch-project/data-prepper --search 'milestone:$ARGUMENTS' --state closed --json number,url,title,labels,body --limit 200
18+
```
19+
20+
```
21+
gh pr list --repo opensearch-project/data-prepper --search 'milestone:$ARGUMENTS' --state closed --json number,url,title,labels,body --limit 200
22+
```
23+
24+
Collect all results. Note which items are issues vs PRs.
25+
26+
## Step 2: Read the Label-to-Category Mapping
27+
28+
Read the file `release/script/release-notes/label-category-mapping.md` for the full rules
29+
on how labels map to categories, how to distinguish Features from Enhancements, what to
30+
exclude, and what to consolidate.
31+
32+
## Step 3: Read Example Release Notes for Style
33+
34+
Read 2-3 of the most recent release notes files in `release/release-notes/`. Use only
35+
files matching `data-prepper.release-notes-*.md` -- ignore `data-prepper.change-log-*.md`
36+
files, which are a different format. Study the tone, format, and level of detail.
37+
Key style observations:
38+
39+
- Each item is a single bullet point: `* Description ([#N](url))`
40+
- Descriptions are concise, active, and user-facing
41+
- They describe what changed from the user's perspective, not implementation details
42+
- Multiple related links can appear: `([#N1](url1), [#N2](url2))`
43+
- Security items use the format: `* CVE-XXXX-XXXXX - library version ([#N](pr-url))`
44+
- Lead with the CVE identifier(s), then the library name and the version that fixes it
45+
- Link to the PR that performed the upgrade, not the vulnerability issue
46+
- If multiple CVEs are fixed by the same upgrade PR, combine them on one line:
47+
`* CVE-XXXX-XXXXX, CVE-YYYY-YYYYY - library version ([#N](pr-url))`
48+
- Search for the fixing PR by looking up the CVE or library name in closed PRs
49+
- The date format is YYYY-MM-DD
50+
- Empty categories are kept in the output (the heading with no items below it)
51+
52+
## Step 4: Categorize Each Item
53+
54+
For each issue/PR:
55+
56+
1. **Check exclusion rules first.** Skip release prep PRs, changelog PRs, release notes PRs,
57+
individual dependency bumps, license header updates, and bot housekeeping PRs.
58+
59+
2. **Apply label-based categorization.** Use the mapping rules to assign a category.
60+
61+
3. **Confirm by reading the body.** If the labels suggest one category but the body clearly
62+
indicates another, override the label-based assignment. Pay special attention to:
63+
- Distinguishing Features (new capability) from Enhancements (improving existing)
64+
- Items labeled `enhancement` that are actually bug fixes
65+
- Items with no relevant labels -- categorize based on the body content
66+
67+
4. **Consolidate related items.** When an issue and its implementing PR(s) are both in the
68+
milestone, produce one line. Prefer linking to the issue. If a PR has no corresponding
69+
issue, link to the PR.
70+
71+
## Step 5: Reword Each Item
72+
73+
Rewrite each item to be:
74+
75+
- **Direct and concise**: "Support X" not "Add support for X", "Added support for X",
76+
or "Support for X was added". Lead with the verb, skip filler words.
77+
- **User-facing**: Describe the impact, not the implementation. "Support compressed files
78+
in the file source" not "Add GzipInputStream wrapper to FileSource class"
79+
- **Concise**: One sentence, no trailing periods
80+
- **Specific**: Name the plugin or component when relevant. "Support partition keys in the
81+
OTel metrics source with persistent buffers" not "Support partition keys"
82+
83+
Do NOT use the prefix tags like "feat:", "fix:", "refactor:" from commit messages.
84+
85+
## Step 6: Produce the Output
86+
87+
Write the release notes file to:
88+
`release/release-notes/data-prepper.release-notes-VERSION.md`
89+
90+
where VERSION is derived from the milestone (e.g. milestone `v2.15` produces version `2.15.0`
91+
if it's a minor release).
92+
93+
Use today's date in the header.
94+
95+
Format:
96+
97+
```
98+
## YYYY-MM-DD Version M.m.p
99+
100+
---
101+
102+
### Breaking Changes
103+
104+
* Item ([#N](url))
105+
106+
### Features
107+
108+
* Item ([#N](url))
109+
110+
### Enhancements
111+
112+
* Item ([#N](url))
113+
114+
### Bug Fixes
115+
116+
* Item ([#N](url))
117+
118+
### Security
119+
120+
* Item ([#N](url))
121+
122+
### Maintenance
123+
124+
* Item ([#N](url))
125+
126+
```
127+
128+
Keep all six category headings even if a category has no items.
129+
130+
## Step 7: Review
131+
132+
After writing the file, read it back and check:
133+
- No duplicate items
134+
- No excluded items leaked through
135+
- Items are in the correct categories
136+
- Wording is consistent in style
137+
- All links are correct
138+
139+
Present the final file to the user and note any items where categorization was uncertain
140+
so they can review those specifically.

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,5 +30,6 @@ pipelines.yaml
3030
run-dataprepper.sh
3131
trace-tester.py
3232

33-
# Claude project instructions
33+
# Claude Code
34+
.claude/settings.local.json
3435
CLAUDE.md

‎release/script/release-notes/README.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,45 @@
11
# Generate Release Notes
22

3-
To help generate release notes, you can use the following script.
4-
It will produce a formatted file, but you need to organize the content and possibly reword or remove.
3+
## AI-Assisted Generation (Recommended)
4+
5+
Use an AI coding assistant to generate categorized, reworded release notes from the GitHub
6+
milestone. The prompt is checked into the repository and can be used with any AI tool.
7+
8+
The prompt file is at: `.claude/commands/generate-release-notes.md`
9+
10+
### Using Claude Code
11+
12+
Claude Code loads this as a slash command automatically:
13+
14+
```
15+
/generate-release-notes v2.15
16+
```
17+
18+
### Using Kiro or Other AI Tools
19+
20+
Ask the AI to read and follow the prompt file, providing the milestone version:
21+
22+
> Read and follow the instructions in `.claude/commands/generate-release-notes.md` for milestone v2.15
23+
24+
### What the AI Does
25+
26+
1. Fetches closed issues and PRs for the milestone using the GitHub CLI
27+
2. Categorizes each item using labels and PR body content (see `label-category-mapping.md`)
28+
3. Rewords items to be active, concise, and user-facing
29+
4. Consolidates related issues/PRs into single entries
30+
5. Excludes internal items (dependency bumps, release prep, license headers)
31+
6. Writes the release notes file to `release/release-notes/`
32+
33+
You should review the output, especially any items the AI flags as uncertain.
34+
35+
### Prerequisites
36+
37+
* [GitHub CLI](https://cli.github.com/) - must be authenticated
38+
* An AI coding assistant (Claude Code, Kiro, etc.)
39+
40+
## Manual Generation (Legacy)
41+
42+
To generate a flat, uncategorized list that requires manual organization:
543

644
You need two tools installed:
745

‎release/script/release-notes/label-category-mapping.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Label to Category Mapping for Release Notes
2+
3+
This file defines how GitHub labels map to release note categories.
4+
It is referenced by the release notes generation prompt.
5+
6+
## Categories
7+
8+
The release notes use these fixed categories, in this order:
9+
10+
1. **Breaking Changes**
11+
2. **Features**
12+
3. **Enhancements**
13+
4. **Bug Fixes**
14+
5. **Security**
15+
6. **Maintenance**
16+
17+
## Label Mapping Rules
18+
19+
### Breaking Changes
20+
- `breaking change`
21+
22+
### Bug Fixes
23+
- `bug`
24+
25+
### Security
26+
- `security fix`
27+
- `Mend: dependency security vulnerability`
28+
29+
### Maintenance
30+
- `maintenance`
31+
- `dependencies`
32+
- `ci`
33+
- `github_actions`
34+
- `documentation`
35+
36+
### Features vs Enhancements
37+
38+
Both Features and Enhancements often use the `enhancement` label. Use these rules to distinguish:
39+
40+
**Features** (entirely new capabilities):
41+
- Introduces a new source, processor, sink, or buffer plugin
42+
- Adds a wholly new integration (e.g. new AWS service support)
43+
- Adds a new expression function or operator
44+
- The issue/PR title or body describes something that did not exist before
45+
46+
**Enhancements** (improvements to existing capabilities):
47+
- Adds a configuration option to an existing plugin
48+
- Improves performance of an existing feature
49+
- Extends an existing plugin to support a new format, codec, or protocol
50+
- The `ease-of-use` or `performance` labels are present
51+
52+
When the `enhancement` label alone is present, read the PR/issue body to determine which category applies.
53+
54+
## Items to Exclude
55+
56+
Do not include items in the release notes for:
57+
- Release preparation PRs (e.g. "Prepare release X.Y.Z", version bumps for the release)
58+
- Changelog and release notes PRs themselves
59+
- Individual dependabot/Mend dependency bump PRs (summarize these under Maintenance if there are notable upgrades, otherwise omit)
60+
- PRs that only update license headers, fix typos in code comments, or fix test flakiness with no user-facing impact
61+
- PRs from bots that are purely automated housekeeping
62+
63+
## Items to Consolidate
64+
65+
- When an issue and one or more PRs address the same feature/fix, produce a single release note line referencing the issue (preferred) or the primary PR
66+
- When multiple PRs implement parts of the same feature, consolidate into one line

0 commit comments

Comments
 (0)