Skip to content

claude: generate-release-notes slash command #1471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
istio-testing merged 1 commit into from
Jan 2, 2026
Merged

claude: generate-release-notes slash command #1471

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions .claude/commands/generate-release-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
You are an expert at analyzing git history and creating comprehensive release notes for the Sail Operator project.

## Task

Generate professional release notes for a Sail Operator release. The release notes should be comprehensive, well-organized, and follow industry best practices.

## Process

1. **Determine the release scope:**
- Ask the user which version to generate notes for (or detect from current branch/tags)
- Identify the previous release to compare against
- Find all merged PRs and commits between the two versions

2. **Analyze and categorize changes:**
- Fetch all merged PRs between releases using `gh pr list`
- Parse PR titles, descriptions, and labels to understand the changes
- Check for linked issues to understand the "why" behind changes
- Identify Istio version updates from `versions.yaml` changes
- Identify first-time contributors by checking if they have commits before the previous release
- Group changes into categories (USER-FACING ONLY):
- **Breaking Changes** (API changes, deprecations)
- **New Features** (enhancements, new capabilities)
- **Bug Fixes** (fixes, patches)
- **Istio Version Support** (new Istio versions added)
- **Documentation** (doc updates)
- OMIT: Internal/Development changes, test improvements, CI/CD, dependency updates (unless security-related)

3. **Generate comprehensive release notes with these sections:**

```markdown
# Sail Operator [VERSION]

Released: [DATE]

## Overview
[2-3 sentence summary of the release - major themes, Istio versions supported, key improvements]

## Supported Istio Versions
This release supports the following Istio versions:
- Istio 1.28.x (1.28.0, 1.28.1)
- Istio 1.27.x (1.27.0 - 1.27.4)
- Istio 1.26.x (1.26.0 - 1.26.7)
[Auto-detect from versions.yaml - only list non-EOL versions]

## ⚠️ Breaking Changes
[List any breaking changes with detailed migration guidance and code examples]

## ✨ New Features
- **Feature Name** - Description of what it does and why it's useful ([#PR](https://github.com/istio-ecosystem/sail-operator/pull/PR))
[Group related features under subheadings for better organization]

## 🐛 Bug Fixes
- **Issue description** - What was fixed and impact ([#PR](https://github.com/istio-ecosystem/sail-operator/pull/PR), fixes [#issue](https://github.com/istio-ecosystem/sail-operator/issues/issue))
[Keep concise, focus on user-visible bugs only]

## 📚 Documentation
[Organize by topic with subheadings]
- List significant doc improvements that help users

## Upgrade Notes
[Any special considerations when upgrading from previous version]

## Contributors

### 🎉 First-Time Contributors
A special welcome to our new contributors!
[List first-time contributors with GitHub handles and links to their first PR]

### All Contributors
Thank you to all contributors who made this release possible!
[List of all contributors with GitHub handles]

## Installation

See the [installation documentation](https://github.com/istio-ecosystem/sail-operator/blob/main/docs/README.adoc) for installation instructions.

**Full Changelog**: https://github.com/istio-ecosystem/sail-operator/compare/[PREV]...[CURRENT]
```

4. **Quality checks:**
- Ensure all categories have content (omit empty sections except Breaking Changes - always show even if empty)
- Verify PR and issue links are correct
- Check that Istio versions match what's in versions.yaml
- Use clear, user-focused language (avoid internal jargon)
- Highlight impact and benefits, not just what changed

5. **Output:**
- Display the formatted release notes
- Offer to save to a file (e.g., `release-notes-[VERSION].md`)
- Offer to update the GitHub release with these notes using `gh release edit`

## Example PR Analysis

When you see a PR titled "Add support for manifest customization (#123)", analyze it to understand:
- The feature enables users to customize Istio manifests
- It implements SEP-3
- It's a new feature (enhancement label)
- Should be in "New Features" section with user-focused description

## Best Practices

- **User-centric language**: Write for operators/admins deploying Istio, not developers
- **Highlight value**: Explain WHY changes matter, not just WHAT changed
- **Link everything**: PRs, issues, documentation
- **Be specific**: "Fixed istiod crash on nil pointer" not "Fixed bug"
- **Group intelligently**: Related changes together (e.g., all ambient mode improvements)
- **Surface important items**: Breaking changes and major features at the top
- **Include examples**: For new features, show basic usage if possible
- **Migration guidance**: For breaking changes, explain how to adapt

## Special Considerations

- **Automated PRs**: Dependency updates from bots should be omitted entirely
- **Bot Contributors**: Exclude bot accounts (e.g., openshift-service-mesh-bot, istio-testing) from the Contributors section - only list human contributors
- **Backport PRs**: Count the original change, not each backport
- **Version bumps**: When operator version is bumped for Istio support, highlight new Istio versions prominently
- **Security fixes**: Clearly mark security-related fixes
- **Deprecations**: Clearly warn about deprecated features with timeline
- **Internal/Test changes**: NEVER include testing improvements, CI/CD changes, or internal refactoring - these are not relevant to users
- **Focus on user impact**: Only include changes that directly affect users deploying and operating Istio with Sail Operator
- **GitHub Links**: Always convert PR and issue references to full GitHub links (e.g., #123 → [#123](https://github.com/istio-ecosystem/sail-operator/pull/123))
- **First-time Contributors**: Identify contributors who have never contributed before this release and highlight them separately

## Commands to Use

```bash
# Get all merged PRs between releases
gh pr list --state merged --base main --json number,title,labels,author,mergedAt,body --limit 500

# Get commits between tags
git log --oneline [PREV_TAG]..[CURRENT_TAG]

# Get all contributors (excluding bots)
git log [PREV_TAG]..[CURRENT_TAG] --format="%an" | sort -u | grep -v -E "(bot|automation|automator)"

# Identify first-time contributors (those who don't have commits in history up to PREV_TAG, excluding bots)
git log [PREV_TAG]..[CURRENT_TAG] --format="%an" | sort -u | grep -v -E "(bot|automation|automator)" > /tmp/current_contributors.txt
git log [PREV_TAG] --format="%an" | sort -u | grep -v -E "(bot|automation|automator)" > /tmp/all_previous_contributors.txt
comm -23 /tmp/current_contributors.txt /tmp/all_previous_contributors.txt

# Get GitHub username for a contributor
git log [PREV_TAG]..[CURRENT_TAG] --author="Author Name" --format="%an <%ae>" | head -1

# Check versions.yaml for Istio versions
cat pkg/istioversion/versions.yaml

# Update GitHub release
gh release edit [TAG] --notes-file release-notes.md
```

Remember: Great release notes help users decide whether to upgrade, understand what changed, and successfully migrate. They're a critical communication tool for the project.
Loading