release-notes

Release Notes

Overview

This skill generates structured release notes by analyzing git history. It determines the version range from git tags, categorizes commits by type, identifies contributors, and produces a comprehensive RELEASE_NOTES.md. A brief interview confirms version number, highlights, and breaking changes before final output.

Instructions

Phase 1: Discovery & Analysis

1. Determine the version range to document:

   • Run git tag --sort=-version:refname to find existing tags.
   • If tags exist, use the range from the most recent tag to HEAD.
   • If no tags exist, use AskUserQuestion to ask the user for the range (e.g., a specific commit SHA, "last 20 commits", or "all history").
   • The user may also specify a custom range as an argument (e.g., /release-notes v1.0.0..v1.1.0).

2. Collect commit history for the determined range:

   • Run git log <range> --pretty=format:"%H|%an|%ae|%s|%b" --no-merges to get commit details.
   • Run git log <range> --pretty=format:"%H|%an|%ae|%s|%b" --merges to identify PR merges.
   • Run git shortlog -sne <range> to gather contributor information.

3. Categorize each commit based on its message prefix or content:

   • Features: Messages starting with feat, add, new, or containing "added", "implement"
   • Bug Fixes: Messages starting with fix, bugfix, or containing "fixed", "resolve"
   • Breaking Changes: Messages containing BREAKING CHANGE, BREAKING:, or using ! after type (e.g., feat!:)
   • Improvements: Messages starting with refactor, improve, update, perf, enhance
   • Documentation: Messages starting with docs, doc
   • Other: Messages starting with chore, ci, build, test, style, or anything else

4. For each category, extract a clean one-line summary from the commit message subject line. Strip conventional commit prefixes (e.g., feat: add login becomes Add login).

5. Identify potential highlights by looking for:

   • Commits with long bodies (detailed explanations suggest significance)
   • Breaking changes
   • Features with multiple related commits
   • Merge commits from PRs (often represent larger changes)

Phase 2: Brief Interview

6. Present the analysis summary to the user via AskUserQuestion and confirm:

   Round 1 - Version & Highlights:

   • "What version number should this release be?" (suggest based on changes: major if breaking, minor if features, patch if fixes only)
   • "Here are the auto-detected highlights: [list]. Would you like to adjust, add, or remove any?" (provide options: "Looks good", "I'll adjust", with space for custom input)

   Round 2 - Breaking Changes & Extras (only if applicable):

   • If breaking changes were detected: "The following breaking changes were found: [list]. Do any of these need a migration guide?"
   • "Any additional notes to include in the release? (e.g., deprecation notices, known issues, acknowledgments)"

Phase 3: Output

7. Read the template file at skills/release-notes/output-template.md and use it as the structure for generating RELEASE_NOTES.md in the project root.
   • Replace vX.Y.Z with the confirmed version number.
   • Replace YYYY-MM-DD with today's date.
   • Fill each section with the categorized commit data from Phase 1 and interview answers from Phase 2.
8. Omit sections that have no entries (e.g., if there are no breaking changes, skip that section entirely).
9. Write the file and inform the user of the output location.

Examples

Input

/release-notes

(In a project with git tag v1.2.0 and 15 commits since that tag)

Phase 1 Output (internal analysis)

Range: v1.2.0..HEAD (15 commits)

Categorized:
- Features (3): Add OAuth login, Add user avatar upload, Add dark mode toggle
- Bug Fixes (5): Fix session timeout, Fix mobile nav overlap, ...
- Improvements (4): Refactor auth middleware, Improve query performance, ...
- Other (3): Update CI config, Add unit tests for auth, ...

Contributors: alice (7), bob (5), charlie (3)
Suggested version: v1.3.0 (minor - new features, no breaking changes)

Interview Round 1

Questions:
1. "Based on the changes (3 new features, no breaking changes), the suggested
    version is v1.3.0. What version should this release be?"
    Options: ["v1.3.0 (Recommended)", "v1.2.1 (patch)", "v2.0.0 (major)"]

2. "Auto-detected highlights: OAuth login support, dark mode toggle, and
    significant auth middleware refactoring. Would you like to adjust these?"
    Options: ["Looks good", "I'll provide my own"]

Output

# Release Notes - v1.3.0

> Released: 2025-01-15

## Highlights
- OAuth login support enabling Google and GitHub authentication
- Dark mode toggle with system preference detection
- Significant performance improvements in authentication flow

## Features
- Add OAuth login with Google and GitHub providers
- Add user avatar upload with image cropping
- Add dark mode toggle with system preference detection

## Bug Fixes
- Fix session timeout not redirecting to login page
- Fix mobile navigation menu overlapping content
- Fix password reset email not sending in production
- Fix race condition in concurrent API requests
- Fix incorrect timezone display in user profile

## Improvements
- Refactor auth middleware for better extensibility
- Improve database query performance for user listings
- Update error messages to be more descriptive
- Enhance logging format for production debugging

## Contributors
- @alice (7 commits)
- @bob (5 commits)
- @charlie (3 commits)

Guidelines

• Commit messages are the primary data source. If they are poor quality (e.g., "fix", "wip", "update"), do your best to infer meaning from the diff summary or group them under "Other".
• Never fabricate changes. Every item in the release notes must correspond to an actual commit.
• Keep descriptions concise but informative. Transform terse commit messages into readable sentences where possible (e.g., fix: nav overlap on mobile becomes "Fix mobile navigation menu overlapping content").
• If the project uses GitHub PRs, prefer PR titles over individual commit messages when available, as they tend to be more descriptive.
• The interview should be brief (1-2 rounds maximum). The value is in automation, not interrogation.
• If the user passes a file path argument, write the output to that path instead of the project root.
• Respect existing RELEASE_NOTES.md or CHANGELOG.md files. If one exists, ask whether to append, prepend, or create a new file.
• Use the contributor's git name as-is. Don't attempt to resolve GitHub usernames unless the information is available in the commit metadata.
• Date in the release notes should be the date of generation (today), not the date of the last commit.