release-notes

name	release-notes
description	Generate a GitHub release note draft for this Obsidian plugin repository. Use when the user asks to write, draft, or prepare release notes for a new version. Invoked with a version number argument (e.g. "0.11.0", "0.11.0-preview.1"). Analyzes git history and code diffs since the previous release to produce user-facing release notes in the project's established format.

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.

Upgrade section

Always present. Keep it short and plain — no links, no blockquotes, no extra formatting.

• For patch/preview: Simply update from v{prev} — no configuration needed. or Update from v{prev}. No configuration changes needed.
• For stable 0.X.0: Update from v{prev} — no extra configuration required. with additional migration notes if there are breaking changes.
• If there are breaking changes, add a ⚠ warning with specific user action required.

New Contributors section

Only include if there are new contributors. Use this exact format:

- @username made their first contribution in #PR

Do not add bold formatting, descriptions, or extra text. Do not add a "Welcome" message.

For stable releases: re-list contributors who were first listed in a prerelease within this cycle. They are still "new" from the stable user's perspective.

Closing

Always end with this exact line:

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

Writing principles

• User perspective only: Describe benefits and behavior, not code changes. Never mention internal identifiers like component names, hook names, framework APIs, algorithm details, or data structures. The reader is an Obsidian user, not a developer reading the source code.
• Accuracy over speed: Read the actual code diffs. A commit message saying "fix: resolve issue" tells you nothing — the diff tells you everything.
• Be specific: "Fixed agents failing to start on NixOS" is better than "Fixed shell compatibility issue." Include concrete details like error messages or specific scenarios.
• One item per logical change: A single commit fixing process cleanup across platforms is one item. A single commit fixing two unrelated bugs is two items. Match the logical boundary, not the commit boundary.
• Consistent tense: Use past tense for fixes ("Fixed..."), present tense or imperative for features ("See how much context you've used" / "Attach non-image files").
• Performance items describe the user experience: "Significantly improved responsiveness for long sessions" — not "Added virtual scrolling with @tanstack/react-virtual and RAF batching."

Examples

These are real release notes from this repository. Study the tone, format, and level of detail.

Example 1: Bug fix release (v0.10.2)

🐛 **Bug Fix Release (v0.10.2)**

### 🐛 Fixes:

- **🪟 WSL Distribution Names with Dots**: Fixed "Invalid WSL distribution name" error when specifying versioned distribution names like `Ubuntu-22.04`. (#223)

### 🚀 Upgrade:

Simply update from v0.10.1 — no configuration needed.

--------

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

Note: One fix, one item. Short title tells you the topic. Description includes the actual error message for specificity. No extra sections.

Example 2: Preview release (v0.10.0-preview.3)

🔬 **Preview Release (v0.10.0-preview.3)**

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

### 🐛 Fixes:

- **🧹 Process Cleanup on Exit**: Fixed agent child processes (e.g., MCP server nodes) remaining after closing Obsidian, restarting agents, or switching sessions. The plugin now kills the entire process tree on disconnect using platform-specific strategies. Also added cleanup on plugin disable. (#205)

### 🚀 Upgrade:

Update from v0.10.0-preview.2. No configuration changes needed.

--------

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

Note: The prerelease warning is always included. A multi-faceted fix (multiple platforms, multiple triggers) is still ONE item because it's one logical concern. "platform-specific strategies" is acceptable — it communicates the scope without naming specific APIs.

Example 3: Feature release with aggregated prereleases (v0.9.0, excerpt)

✨ **Feature Release (v0.9.0)**

This release adds context usage tracking, file attachment support, agent update notifications, dynamic session configuration, and a chat export command.

### 🌟 New:

- **📊 Context Usage Indicator**: See how much of the agent's context window you've used, displayed next to the send button. Color changes at 70%/80%/90% thresholds to warn you before hitting limits. (#113)
- **📎 File Attachments**: Attach non-image files (text, code, PDFs, etc.) to your messages via paste or drag-and-drop. Files are sent as `resource_link` content and rendered in chat messages. (#77)

### 🔧 Improvements:

- **📦 ACP SDK Update**: Updated @agentclientprotocol/sdk to v0.14.1.

### 🐛 Fixes:

- **📜 Auto-Scroll Threshold**: Increased threshold from 20px to 35px for more reliable scroll tracking.
- **🔗 Settings Documentation Link**: Fixed clicking the documentation link in settings causing Obsidian popout windows to close due to missing `target="_blank"`. (#152)

### 🚀 Upgrade:

Update from v0.8.3 — no extra configuration required. New features activate automatically when supported by your agent.

--------

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

Note: Summary paragraph lists the highlights. Features describe what users can now do. SDK update is a one-liner. Fixes describe the user-visible symptom, not the code fix.

Example 4: Improvement & bug fix release with new contributor (v0.9.4)

🔧 **Improvement & Bug Fix Release (v0.9.4)**

This release adds a copy button to messages, fixes markdown overflow issues, and improves floating chat behavior.

### 🌟 New:

- **📋 Copy Message Button**: Hover over any message to reveal a copy-to-clipboard button. Works for both user and assistant messages. (#189)

### 🔧 Improvements:

- **🪟 Smarter Floating Chat Commands**: Floating chat commands (open, minimize, close) now only appear in the command palette when the feature is enabled. Minimize and close additionally require a focused floating window. (#188)

### 🐛 Fixes:

- **📜 Horizontal Scroll for Wide Content**: Fixed mermaid diagrams, tables, and SVGs being clipped instead of scrolling horizontally. (#190)
- **🪟 Floating Chat Toggle**: Fixed floating chat button not hiding when the feature is toggled off in settings. (#187)

### 🚀 Upgrade:

Simply update from v0.9.3 — no configuration needed.

--------

### 👋 New Contributors

- @aviatesk made their first contribution in #187

--------

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

Note: Even though it has a "New" section, the overall release type is "Improvement & Bug Fix Release" because the copy button is a small addition, not a major feature. New Contributors uses the exact @username made their first contribution in #PR format with no extra decoration.

Example 5: Feature release with breaking changes (v0.7.0, excerpt)

✨ **Feature Release (v0.7.0)**

This release introduces multi-agent session support, allowing you to run multiple independent agent conversations simultaneously in separate chat views.

### 🌟 New:

- **🪟 Multi-Agent Sessions**: Run multiple agents simultaneously in separate chat views. Each view has its own independent agent process and session. (#59)
- **📢 Broadcast Commands**: Control multiple chat views at once:
  - `Broadcast prompt`: Copy the active view's input to all other views
  - `Broadcast send`: Send messages in all views simultaneously
  - `Broadcast cancel`: Cancel operations in all views
- **🔀 Focus Navigation**: Quickly switch between chat views with `Focus next/previous chat view` commands
- **➕ Open New View Command**: Open additional chat views via command palette or Header Menu

### 🔧 Improvements:

- **🍔 Header Menu**: New ellipsis menu in chat header for quick agent switching, opening new views, restarting agent, and accessing plugin settings.
- **🚨 Error Overlay**: Errors are now displayed as a dismissible overlay above the input area instead of replacing the entire chat.

### ⚠ Breaking Changes:

- **Setting Renamed**: `activeAgentId` → `defaultAgentId` (automatically migrated)

### 🚀 Upgrade:

Update from v0.6.1 — Settings are automatically migrated. Multi-session support works immediately with existing agent configurations.

--------

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

Note: The summary focuses on the single biggest highlight (multi-agent sessions), not a list of everything. Breaking changes get their own section even when migration is automatic — users need to know. The Upgrade section mentions the auto-migration. Sub-bullet lists (as in Broadcast Commands) are fine when they improve scannability. Each distinct capability (Focus Navigation, Open New View) gets its own item rather than being folded into Multi-Agent Sessions.