Release Notes

Release Notes Generator

Generate a release note draft for this repository by analyzing git changes since the previous release. The output is a Markdown code block ready to paste into a GitHub release — do NOT create the release itself.

The version number is provided as an argument (e.g. /release-notes 0.11.0). If no version is given, ask for one before proceeding.

Step 1: Determine the previous release

The "previous release" depends on the version type being drafted:

• Stable version (no -preview): Find the most recent stable tag, skipping all prereleases. This is because stable release notes cover everything since the last stable release — they aggregate all prerelease changes into one cohesive set of notes.
• Prerelease (-preview.N): Find the most recent tag of any kind (stable or prerelease). Prerelease notes only cover the incremental delta since the last tag.

Use git tag --sort=-v:refname to list tags and pick the right one. Confirm the previous tag to the user before continuing (e.g. "Previous release: v0.10.2 — generating notes for changes since then.").

Step 2: Gather information

Run these in parallel where possible:

1. Commit log: git log {prev_tag}..HEAD --oneline — the list of changes
2. Diff stat: git diff --stat {prev_tag}..HEAD — which files changed
3. Actual diffs: Read the diffs of changed source files (src/, styles.css, manifest.json, etc.) to understand what each change actually does at the code level. This is critical — commit messages alone are not enough to write accurate user-facing descriptions.
4. Issue numbers: Extract #NNN references from commit messages. Note: commit messages often contain PR numbers (from merge commits), not the original issue numbers. Use whatever #NNN is in the commit message as-is — the author will verify and correct these during review.
5. New contributors: Compare authors before and after the previous tag:

   git log --format='%aN' {prev_tag} | sort -u        # existing contributors
   git log --format='%aN' {prev_tag}..HEAD | sort -u   # contributors in this range

   Anyone in the second set but not the first is a new contributor. To find their GitHub username and PR number, use git log --format='%aN <%aE>' {prev_tag}..HEAD and cross-reference with #NNN in their commit messages. The GitHub username may differ from the git author name — check the commit on GitHub if needed.
6. Previous prerelease notes (stable releases only): If drafting a stable release and there were prereleases in the range, read their release notes with gh release view {tag}. This helps identify bugs that were introduced and fixed within the prerelease cycle — those should be excluded from the stable release notes since they never affected stable users.

Step 3: Analyze and categorize

Before writing, think through what each change means from a user's perspective:

• What can users do now that they couldn't before? → New features (🌟 New)
• What existing behavior got better? → Improvements (🔧 Improvements)
• What was broken and is now fixed? → Bug fixes (🐛 Fixes)
• Did anything get faster? → Performance (⚡ Performance)
• Does anything require user action on upgrade? → Breaking changes (⚠ Breaking Changes)

For stable releases aggregating prereleases: exclude bugs that were both introduced and resolved during the prerelease cycle. Those never affected stable users and do not belong in the stable release notes.

Detecting breaking changes

Breaking changes are easy to miss in diffs. Actively look for these patterns:

• Renamed settings keys in default settings or settings types (e.g., activeAgentId → defaultAgentId)
• Renamed command IDs in plugin.ts addCommand() calls
• Changed or removed public APIs or exported interfaces
• Changed default behavior that users relied on (e.g., a button that now does something different)
• Removed features or settings

If any are found, they MUST appear in the ### ⚠ Breaking Changes: section AND be mentioned in the Upgrade section. If the migration is automatic, say so — users still need to know something changed.

Step 4: Write the draft

Output the release note as a single Markdown code block. Follow this format exactly.

Title line

The title is plain text with bold formatting — NOT a Markdown heading. No # prefix.

{emoji} **{Release Type} (v{version})**

Choose the release type and emoji based on content:

• 🔬 **Preview Release** — all prereleases
• ✨ **Feature Release** — stable with new features
• 🔧 **Improvement & Bug Fix Release** — stable with improvements and fixes but no major new features
• 🐛 **Bug Fix Release** — stable with only bug fixes
• 🔧 **Improvement Release** — stable with only improvements
• ⚡ **Performance Fix** — stable with only performance changes
• 🔧 **Maintenance Release** — stable with only dependency updates or internal changes

Prerelease warning (prereleases only)

For ALL preview releases — regardless of size — add this immediately after the title line (with a blank line before and after):

⚠ **This is a preview release** — Features are experimental and may change. Please report any issues!

This is mandatory for every prerelease. Never omit it.

Summary paragraph

For stable 0.X.0 releases and substantial prereleases with multiple features, add a 1-2 sentence summary after the title (or after the prerelease warning). Patch releases and small prereleases with a single change can skip this.

The summary should focus on the single biggest highlight or theme — not enumerate every change. One sentence is ideal. If you can't pick a single theme, pick the top 2-3 and keep it under two sentences.

Sections

Include only sections that have content, in this order:

### ⚡ Performance:

### 🌟 New:

### 🔧 Improvements:

### 🐛 Fixes:

### ⚠ Breaking Changes:

### 🚀 Upgrade:

--------

### 👋 New Contributors

--------

**Thank you for your continued support! Your feedback helps make this plugin better for everyone.** 🙏

Item format

Each item follows this pattern:

- **{emoji} {Short Title}**: {Description}. (#issue)

Rules:

• The emoji indicates the category (🪟 window/floating, ⌨ keyboard/input, 📋 copy/clipboard, 🔗 links/paths, 🐧 Linux/WSL, 🍎 macOS, 📦 packages/SDK, 🔔 notifications, 📂 files/directories, 🔐 permissions, 📊 data/charts, 📜 scrolling, 🔍 search/focus, 🎨 styling/UI, 🖥 terminal, 📝 text/editing, 🔄 sync/restore, 🗑 deletion, 📏 sizing/layout, etc.)
• The short title is 2-5 words, bold, and scannable — readers should understand the topic from the title alone.
• The description explains what changed from the user's perspective. Do not describe implementation details — no function names, class names, React hooks, framework APIs, or internal architecture. If a change is purely internal (refactoring, performance optimization), describe its user-visible effect.
• Issue numbers go at the end in parentheses. Omit if no issue is referenced.
• One item per logical change. If a single commit or PR addresses one concern (e.g. "fix process cleanup"), that is one item — even if it touches multiple files or uses platform-specific strategies. Conversely, don't merge unrelated changes into one item.