Skip to content

Commit 64273ec

Browse files
kb-newrelickb-newrelic
authored
chore: add claude skill for changelog analysis (#490)
1 parent 40c815e commit 64273ec

File tree

2 files changed

+192
-0
lines changed

2 files changed

+192
-0
lines changed

‎.claude/skills/version-bump-analysis/extract-changelog-version.sh‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
#!/bin/bash
2+
3+
# Extract a specific version section from an OpenTelemetry changelog
4+
# Usage: extract-changelog-version.sh <url> <version>
5+
# Example: extract-changelog-version.sh "https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/main/CHANGELOG.md" "v0.144.0"
6+
7+
set -euo pipefail
8+
9+
if [ "$#" -ne 2 ]; then
10+
echo "Usage: $0 <changelog_url> <version>" >&2
11+
echo "Example: $0 'https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/main/CHANGELOG.md' 'v0.144.0'" >&2
12+
exit 1
13+
fi
14+
15+
CHANGELOG_URL="$1"
16+
VERSION="$2"
17+
18+
# Fetch changelog and extract the specific version section
19+
# The version appears in headers like "## v1.50.0/v0.144.0"
20+
# We extract from that header until the next "## " header or "<!-- previous-version -->"
21+
OUTPUT=$(curl -s "$CHANGELOG_URL" | awk -v version="$VERSION" \
22+
'BEGIN { found=0; printing=0 } \
23+
/^## / { if (found) { exit } if ($0 ~ version) { found=1; printing=1; print $0; next } } \
24+
/^<!-- previous-version -->/ { if (printing) { exit } } \
25+
printing { print $0 }')
26+
27+
# Check if version was found
28+
if [ -z "$OUTPUT" ]; then
29+
echo "Error: Version $VERSION not found in changelog at $CHANGELOG_URL" >&2
30+
exit 1
31+
fi
32+
33+
echo "$OUTPUT"
34+
exit 0

‎.claude/skills/version-bump-analysis/skill.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
name: version-bump-analysis
3+
description: |
4+
Analyzes OpenTelemetry Collector component version bumps and compiles a markdown
5+
summary of relevant changes (breaking changes, deprecations, bug fixes) from the
6+
upstream CHANGELOG files. Only includes changes for components used in the nrdot
7+
releases repo. Outputs a formatted comment ready to paste into a GitHub PR.
8+
trigger: /version-bump-analysis
9+
type: agent
10+
parameters:
11+
- name: pr_url
12+
description: "GitHub PR URL containing the version bump (e.g., https://github.com/newrelic/nrdot-collector-releases/pull/488)"
13+
required: true
14+
permissions:
15+
- Read
16+
- Glob
17+
- Bash
18+
---
19+
20+
# Version Bump Analysis Skill
21+
22+
Analyzes OpenTelemetry Collector component version bumps and compiles a markdown summary of relevant changes for PR comments.
23+
24+
## Input
25+
26+
- A GitHub PR URL from the `newrelic/nrdot-collector-releases` repository
27+
- The PR will contain version bumps with a title like "feat: Bump OTEL beta core to v0.144.0"
28+
- The PR description will include version ranges like "v0.142.0...v0.144.0"
29+
30+
## Output Format
31+
32+
Generate a markdown comment that can be pasted directly into the PR, following this structure:
33+
34+
```markdown
35+
### Potentially Relevant changes
36+
37+
#### Contrib v[VERSION]
38+
39+
##### 🛑 Breaking changes 🛑
40+
41+
- [List breaking changes with full descriptions from CHANGELOG]
42+
43+
##### 🚩 Deprecations 🚩
44+
45+
- [List deprecations with full descriptions from CHANGELOG]
46+
47+
##### 🧰 Bug fixes 🧰
48+
49+
- [List bug fixes that may be relevant]
50+
51+
#### Core v[VERSION]
52+
53+
[Same structure as Contrib if there are relevant changes]
54+
```
55+
56+
## ⚠️ IMPORTANT: Use Bash Script for CHANGELOG Files
57+
58+
**Do NOT fetch full CHANGELOG files directly** - they are very large (~66k tokens) and inefficient. Instead, use the provided bash script to extract only the relevant version section:
59+
60+
```bash
61+
.claude/skills/version-bump-analysis/extract-changelog-version.sh <changelog_url> <version>
62+
```
63+
64+
This script efficiently fetches and extracts only the relevant version section using curl and awk.
65+
66+
### Example Usage
67+
68+
```bash
69+
# Extract v0.144.0 from OTel Core CHANGELOG
70+
.claude/skills/version-bump-analysis/extract-changelog-version.sh \
71+
"https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/main/CHANGELOG.md" \
72+
"v0.144.0"
73+
74+
# Extract v0.144.0 from OTel Contrib CHANGELOG
75+
.claude/skills/version-bump-analysis/extract-changelog-version.sh \
76+
"https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/CHANGELOG.md" \
77+
"v0.144.0"
78+
```
79+
80+
## Implementation Steps
81+
82+
1. **Extract list of used components from manifest files**:
83+
- Use Glob to find all `distributions/*/manifest.yaml` files
84+
- Use Read to load each manifest file
85+
- Parse the YAML to extract component names from:
86+
- `receivers:` section
87+
- `processors:` section
88+
- `exporters:` section
89+
- `connectors:` section
90+
- `extensions:` section
91+
- `providers:` section
92+
- Extract component names from gomod paths (e.g., `receiver/filelogreceiver` → `receiver/filelog`)
93+
- Build a set of all unique component names used across all distributions
94+
- Component names in CHANGELOG use format: `receiver/filelog`, `processor/cumulativetodelta`, etc.
95+
96+
2. **Extract version information from the PR**:
97+
- Use `gh pr view <pr_number> --json body --jq .body` to fetch the PR description
98+
- Extract the "from" and "to" versions from the PR description
99+
- The description includes links like: `Beta Core: [v0.142.0...v0.144.0]` and `Beta Contrib: [v0.142.0...v0.144.0]`
100+
101+
3. **Fetch CHANGELOG sections for each version**:
102+
- Contrib CHANGELOG: `https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector-contrib/main/CHANGELOG.md`
103+
- Core CHANGELOG: `https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/main/CHANGELOG.md`
104+
- **Use the extract-changelog-version.sh script** to efficiently extract only the relevant version sections
105+
- For each version in the range, call: `.claude/skills/version-bump-analysis/extract-changelog-version.sh <url> <version>`
106+
- This returns only the relevant section for that version (typically <1000 lines vs 66k+ for full file)
107+
- The script will exit with status 1 if the version is not found, allowing error detection
108+
109+
4. **Parse version sections**:
110+
- For each version between "from" and "to" (inclusive of "to", exclusive of "from")
111+
- Extract sections marked as:
112+
- `### 🛑 Breaking changes 🛑` or `## 🛑 Breaking changes 🛑`
113+
- `### 🚩 Deprecations 🚩` or `## 🚩 Deprecations 🚩`
114+
- `### 🧰 Bug fixes 🧰` or `## 🧰 Bug fixes 🧰`
115+
- Preserve the full descriptions and component names from the CHANGELOG
116+
117+
5. **Filter for component relevance**:
118+
- Only include CHANGELOG entries that mention components from the manifest files
119+
- Match component names like `receiver/filelog`, `processor/batch`, `exporter/otlp`, etc.
120+
- Include entries where the component name appears at the start of the bullet point
121+
- Format: `` `component/name`: description ``
122+
- Also include changes to core collector functionality that affect all components (if any)
123+
124+
6. **Format the output**:
125+
- Use the exact emoji and header format from the example
126+
- Preserve markdown formatting from the CHANGELOG
127+
- Include component names in the format `` `component/name`: description ``
128+
- Add clear section headers for Contrib and Core
129+
- Only include sections that have content (omit empty sections)
130+
- If no relevant changes found, output: "No breaking changes, deprecations, or relevant bug fixes found for components used in this repo."
131+
132+
7. **Save the output to a file**:
133+
- Create the `.tmp` directory if it doesn't exist using: `mkdir -p .tmp`
134+
- Write the markdown output to a file in `.tmp` directory with naming pattern: `version-bump-analysis-pr{PR_NUMBER}.md`
135+
- Example: For PR #488, write to `.tmp/version-bump-analysis-pr488.md`
136+
- Use the Write tool to save the formatted markdown content to this file
137+
138+
## Important Notes
139+
140+
- The skill should handle multiple version bumps (e.g., v0.142.0 to v0.144.0 means analyzing both v0.143.0 and v0.144.0)
141+
- Preserve the exact wording from the CHANGELOG - don't summarize or paraphrase
142+
- If there are no breaking changes or deprecations for a section, omit that section entirely
143+
- The output should be ready to copy-paste directly into a GitHub PR comment
144+
- Always include the version number in section headers (e.g., "Contrib v0.144.0")
145+
- If bumping multiple versions, combine changes from all versions into a single output
146+
- **CRITICAL**: Only include changes for components that are listed in the manifest.yaml files
147+
148+
## Component Name Mapping
149+
150+
When matching CHANGELOG entries to manifest components:
151+
- Manifest: `receiver/filelogreceiver` → CHANGELOG: `receiver/filelog`
152+
- Manifest: `processor/batchprocessor` → CHANGELOG: `processor/batch`
153+
- Manifest: `exporter/otlpexporter` → CHANGELOG: `exporter/otlp`
154+
- Pattern: Remove the trailing "receiver", "processor", "exporter", etc. suffix to get the CHANGELOG name
155+
156+
## Example Reference
157+
158+
See https://github.com/newrelic/nrdot-collector-releases/pull/464#issuecomment-3671968859 for the expected output format.

0 commit comments

Comments
 (0)