External/my-claude-code-setup
1
0
Fork 0
mirror of https://github.com/centminmod/my-claude-code-setup.git synced 2025-12-17 23:47:17 +00:00
Code Issues Packages Projects Releases Wiki Activity
my-claude-code-setup/.claude/commands/documentation/create-release-note.md

16 KiB
Raw Permalink Blame History

Release Note Generator

Generate comprehensive release documentation from recent commits, producing two distinct outputs: a customer-facing release note and a technical engineering note.

Interactive Workflow

When this command is triggered, DO NOT immediately generate release notes. Instead, present the user with two options:

Mode Selection Prompt

Present this to the user:

I can generate release notes in two ways:

**Mode 1: By Commit Count**
Generate notes for the last N commits (specify number or use default 10)
→ Quick generation when you know the commit count

**Mode 2: By Commit Hash Range (i.e. Last 24/48/72 Hours)**
Show all commits from the last 24/48/72 hours, then you select a starting commit
→ Precise control when you want to review recent commits first

Which mode would you like?
1. Commit count (provide number or use default)
2. Commit hash selection (show last 24/48/72 hours)

You can also provide an argument directly: /create-release-note 20

Mode 1: By Commit Count

Usage

/create-release-note          # Triggers mode selection
/create-release-note 20       # Directly uses Mode 1 with 20 commits
/create-release-note 50       # Directly uses Mode 1 with 50 commits

Process

  1. If $ARGUMENTS is provided, use it as commit count
  2. If no $ARGUMENTS, ask user for commit count or default to 10
  3. Set: COMMIT_COUNT="${ARGUMENTS:-10}"
  4. Generate release notes immediately

Mode 2: By Commit Hash Range

Workflow

When user selects Mode 2, follow this process:

Step 1: Retrieve Last 24 Hours of Commits

git log --since="24 hours ago" --pretty=format:"%h|%ai|%an|%s" --reverse

Step 2: Present Commits to User

Format the output as a numbered list for easy selection:

Commits from the last 24 hours (oldest to newest):

 1. a3f7e821 | 2025-10-15 09:23:45 | Alice Smith | Add OAuth provider configuration
 2. b4c8f932 | 2025-10-15 10:15:22 | Bob Jones | Implement token refresh flow
 3. c5d9e043 | 2025-10-15 11:42:18 | Alice Smith | Add provider UI components
 4. d6e1f154 | 2025-10-15 13:08:33 | Carol White | Database connection pooling
 5. e7f2g265 | 2025-10-15 14:55:47 | Alice Smith | Query optimization middleware
 6. f8g3h376 | 2025-10-15 16:20:12 | Bob Jones | Dark mode CSS variables
 7. g9h4i487 | 2025-10-15 17:10:55 | Carol White | Theme switching logic
 8. h0i5j598 | 2025-10-16 08:45:29 | Alice Smith | Error boundary implementation

Please provide the starting commit hash (8 characters) or number.
Release notes will be generated from your selection to HEAD (most recent).

Example: "a3f7e821" or "1" will generate notes for commits 1-8
Example: "d6e1f154" or "4" will generate notes for commits 4-8

Step 3: Generate Notes from Selected Commit

Once user provides a commit hash or number:

# If user provided a number, extract the corresponding hash
SELECTED_HASH="<hash from user input>"

# Generate notes from selected commit to HEAD
git log ${SELECTED_HASH}..HEAD --stat --oneline
git log ${SELECTED_HASH}..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short

Important: The range ${SELECTED_HASH}..HEAD means "from the commit AFTER the selected hash to HEAD". If you want to include the selected commit itself, use ${SELECTED_HASH}^..HEAD or count commits with --ancestry-path.

Step 4: Confirm Range

Before generating, confirm with user:

Generating release notes for N commits:
From: <hash> - <commit message>
To:   <HEAD hash> - <commit message>

Proceeding with generation...

Core Requirements

1. Commit Analysis

Determine commit source:

  • Mode 1: COMMIT_COUNT="${ARGUMENTS:-10}" → Use git log -${COMMIT_COUNT}
  • Mode 2: User-selected hash → Use git log ${SELECTED_HASH}..HEAD

Retrieve commits:

  • Use git log <range> --stat --oneline
  • Use git log <range> --pretty=format:"%H|%s|%an|%ad" --date=short
  • Analyze file changes to understand scope and impact
  • Group related commits by feature/subsystem
  • Identify major themes and primary focus areas

2. Traceability

  • Every claim MUST be traceable to specific commit SHAs
  • Reference actual files changed (e.g., src/config.ts, lib/utils.py)
  • Use 8-character SHA prefixes for engineering notes (e.g., 0ca46028)
  • Verify all technical details against actual commit content

3. Length Constraints

  • Each section: ≤500 words (strict maximum)
  • Aim for 150-180 words for optimal readability
  • Prioritize most impactful changes if space constrained

Section 1: Release Note (Customer-Facing)

Purpose

Communicate value to end users without requiring deep technical knowledge. Audience varies by project type (system administrators, developers, product users, etc.).

Tone and Style

  • Friendly & Clear: Write as if explaining to a competent user of the software
  • Value-Focused: Emphasize benefits and capabilities, not implementation details
  • Confident: Use active voice and definitive statements
  • Professional: Avoid jargon, explain acronyms on first use
  • Contextual: Adapt language to the project type (infrastructure, web app, library, tool, etc.)

Content Guidelines

Include:

  • Major new features or functionality
  • User-visible improvements
  • Performance enhancements
  • Security updates
  • Dependency/component version upgrades
  • Compatibility improvements
  • Bug fixes affecting user experience

Exclude:

  • Internal refactoring (unless it improves performance)
  • Code organization changes
  • Developer-only tooling
  • Commit SHAs or file paths
  • Implementation details
  • Internal API changes (unless user-facing library)

Structure Template

## Release Note (Customer-Facing)

**[Project Name] [Version] - [Descriptive Title]**

[Opening paragraph: 1-2 sentences describing the primary focus/theme]

**Key improvements:**
- [Feature/improvement 1: benefit-focused description]
- [Feature/improvement 2: benefit-focused description]
- [Feature/improvement 3: benefit-focused description]
- [Feature/improvement 4: benefit-focused description]
- [etc.]

[Closing paragraph: 1-2 sentences about overall impact and use cases]

Style Examples

✅ Good (Customer-Facing):

"Enhanced authentication system with support for OAuth 2.0 and SAML providers"

❌ Bad (Too Technical):

"Refactored src/auth/oauth.ts to implement RFC 6749 token refresh flow"

✅ Good (Value-Focused):

"Improved database query performance, reducing page load times by 40%"

❌ Bad (Implementation Details):

"Added connection pooling in db/connection.ts with configurable pool size"

✅ Good (User Benefit):

"Added dark mode support with automatic system theme detection"

❌ Bad (Technical Detail):

"Implemented CSS variables in styles/theme.css for runtime theme switching"

Section 2: Engineering Note (Technical)

Purpose

Provide developers/maintainers with precise technical details for code review, debugging, and future reference.

Tone and Style

  • Precise & Technical: Use exact terminology and technical language
  • Reference-Heavy: Include SHAs, file paths, function names
  • Concise: Information density over narrative
  • Structured: Group by subsystem or feature area

Content Guidelines

Include:

  • 8-character SHA prefixes for every commit or commit group
  • Exact file paths (src/components/App.tsx, lib/db/connection.py)
  • Specific technical changes (version numbers, configuration changes)
  • Module/function names when relevant
  • Code organization changes
  • All commits (even minor refactoring)
  • Breaking changes or API modifications

Structure:

  • Group related commits by subsystem
  • List most significant changes first
  • Use single-sentence summaries per commit/group
  • Format: SHA: description (file references)

Structure Template

## Engineering Note (Technical)

**[Primary Focus/Theme]**

[Opening sentence: describe the main technical objective]

**[Subsystem/Feature Area 1]:**
- SHA1: brief technical description (file1, file2)
- SHA2: brief technical description (file3)
- SHA3, SHA4: grouped description (file4, file5, file6)

**[Subsystem/Feature Area 2]:**
- SHA5: brief technical description (file7, file8)
- SHA6: brief technical description (file9)

**[Subsystem/Feature Area 3]:**
- SHA7, SHA8, SHA9: grouped description (files10-15)
- SHA10: brief technical description (file16)

[Optional: List number of files affected if significant]

Style Examples

✅ Good (Technical):

"a3f7e821: OAuth 2.0 token refresh implementation in src/auth/oauth.ts, src/auth/tokens.ts"

❌ Bad (Too Vague):

"Updated authentication system for better token handling"

✅ Good (Grouped):

"c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts)"

❌ Bad (No References):

"Fixed database connection issues"

✅ Good (Precise):

"7b8c9d01: Upgrade react from 18.2.0 to 18.3.1 (package.json)"

❌ Bad (Missing Context):

"Updated React dependency"

Formatting Standards

Markdown Requirements

  • Use ## for main section headers
  • Use **bold** for subsection headers and project titles
  • Use - for bullet lists
  • Use `backticks` for file paths, commands, version numbers
  • Use 8-character SHA prefixes: 0ca46028 not 0ca46028b9fa62bb995e41133036c9f0d6ac9fef

Horizontal Separator

Use --- (three hyphens) to separate the two sections for visual clarity.

Version Numbers

Format as: version X.Y or version X.Y.Z (e.g., "React 18.3", "Python 3.12.1")

File Paths

  • Use actual paths from repository: src/components/App.tsx not "main component"
  • Multiple files: (file1, file2, file3) or (files1-10) for ranges
  • Use project-appropriate path conventions (src/, lib/, app/, pkg/, etc.)

Commit Grouping Strategy

Group When

  • Multiple commits modify the same file/subsystem
  • Commits represent incremental work on same feature
  • Space constraints require consolidation
  • Related bug fixes or improvements

Example Grouping

Individual:
- c4d8a123: Add connection pool configuration
- e5f9b234: Implement pool lifecycle management
- a1c2d345: Add connection pool metrics

Grouped:
- c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts, src/db/metrics.ts)

Don't Group

  • Unrelated commits (different subsystems)
  • Major features (deserve individual mention)
  • Commits with significantly different file scopes
  • Breaking changes (always call out separately)

Quality Checklist

Before finalizing, verify:

  • Mode selection presented (unless $ARGUMENTS provided)
  • Commit range correctly determined (Mode 1: count, Mode 2: hash range)
  • User confirmed commit range before generation
  • Both sections ≤500 words
  • Every claim traceable to specific commit(s)
  • Customer note has no SHAs or file paths
  • Engineering note has SHAs for all commits/groups
  • File paths are accurate and complete
  • Tone appropriate for each audience
  • Markdown formatting consistent
  • Version numbers accurate
  • No typos or grammatical errors
  • Primary focus clearly communicated in both sections
  • Most significant changes prioritized first
  • Language adapted to project type (not overly specific to one domain)

Edge Cases

If Fewer Commits Than Requested

  • Generate notes for all available commits
  • Note this at the beginning: "Release covering [N] commits"
  • Example: "Release covering 7 commits (requested 10)"

If No Commits in Last 24 Hours (Mode 2)

  • Inform user: "No commits found in the last 24 hours"
  • Offer alternatives:
    • Extend time range (48 hours, 7 days)
    • Switch to Mode 1 (commit count)
    • Manual hash range specification

If Mostly Minor Changes

  • Group aggressively by subsystem
  • Lead with most significant changes
  • Note: "Maintenance release with incremental improvements"

If Single Major Feature Dominates

  • Lead with that feature in both sections
  • Group supporting commits under that theme
  • Structure engineering note by feature components

If Merge Commits Present

  • Skip merge commits themselves
  • Include the actual changes from merged branches
  • Focus on functional changes, not merge mechanics

If No Version Tag Available

  • Use branch name or generic title: "Development Updates" or "Recent Improvements"
  • Focus on change summary rather than version-specific language

If User Provides Invalid Commit Hash

  • Validate hash exists: git cat-file -t ${HASH} 2>/dev/null
  • If invalid, show error and re-present commit list
  • Suggest checking the hash or selecting by number instead

Adapting to Project Types

Infrastructure/DevOps Projects

  • Focus on: deployment improvements, configuration management, monitoring, reliability
  • Audience: sysadmins, DevOps engineers, SREs

Web Applications

  • Focus on: features, UX improvements, performance, security
  • Audience: product users, stakeholders, QA teams

Libraries/Frameworks

  • Focus on: API changes, new capabilities, breaking changes, migration guides
  • Audience: developers using the library

CLI Tools

  • Focus on: command changes, new options, output improvements, bug fixes
  • Audience: command-line users, automation engineers

Internal Tools

  • Focus on: workflow improvements, bug fixes, integration updates
  • Audience: team members, internal stakeholders

Example Output Structure

## Release Note (Customer-Facing)

**MyProject v2.4.0 - Authentication & Performance Update**

This release introduces comprehensive OAuth 2.0 support and significant performance improvements across the application.

**Key improvements:**
- OAuth 2.0 authentication with support for Google, GitHub, and Microsoft providers
- Improved database query performance with connection pooling, reducing response times by 40%
- Added dark mode support with automatic system theme detection
- Enhanced error handling and user feedback throughout the interface
- Security updates for dependency vulnerabilities

These enhancements provide a more secure, performant, and user-friendly experience across all application features.

---

## Engineering Note (Technical)

**OAuth 2.0 Integration and Performance Optimization**

Primary focus: authentication modernization and database performance improvements.

**Authentication System:**
- a3f7e821: OAuth 2.0 provider implementation (src/auth/oauth.ts, src/auth/providers/)
- b4c8f932: Token refresh flow and session management (src/auth/tokens.ts)
- c5d9e043: Provider registration UI components (src/components/auth/OAuthProviders.tsx)

**Performance Optimization:**
- d6e1f154: Database connection pooling (src/db/pool.ts, src/db/config.ts)
- e7f2g265: Query optimization middleware (src/db/middleware.ts)

**UI/UX Improvements:**
- f8g3h376, g9h4i487: Dark mode CSS variables and theme switching (src/styles/theme.css, src/components/ThemeProvider.tsx)
- h0i5j598: Error boundary implementation (src/components/ErrorBoundary.tsx)

**Security:**
- i1j6k609: Dependency updates for security patches (package.json, yarn.lock)

Implementation Workflow

When executing this command, Claude should:

If $ARGUMENTS Provided

  1. Use COMMIT_COUNT="${ARGUMENTS}"
  2. Run git commands with the determined count
  3. Generate both sections immediately

If No $ARGUMENTS

  1. Present mode selection prompt to user
  2. Wait for user response

If user selects Mode 1: 3. Ask for commit count or use default 10 4. Generate notes immediately

If user selects Mode 2: 3. Retrieve commits from last 24 hours 4. Present formatted list with numbers and hashes 5. Wait for user to provide hash or number 6. Validate selection 7. Confirm commit range 8. Generate notes from selected commit to HEAD

Final Steps (Both Modes)

  1. Analyze commits thoroughly
  2. Generate both sections following all guidelines
  3. Verify against quality checklist
  4. Present both notes in the specified format