mirror of
https://github.com/rait-09/obsidian-agent-client.git
synced 2026-07-22 06:43:37 +00:00
feat: add release-notes generation skill
Claude Code skill that analyzes git history and code diffs since the previous release to generate a release note draft in the project's established format. Invoked with `/release-notes <version>`.
This commit is contained in:
RAIT-09
parent
8b877b70d9
commit
00944c5075
1 changed files with 331 additions and 0 deletions
331
.claude/skills/release-notes/SKILL.md
Normal file
331
.claude/skills/release-notes/SKILL.md
Normal file
|
|
@ -0,0 +1,331 @@
|
|||
---
|
||||
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:
|
||||
|
||||
```markdown
|
||||
### ⚡ 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.
|
||||
Loading…
Reference in a new issue