External/my-claude-code-setup
1
0
Fork 0
mirror of https://github.com/centminmod/my-claude-code-setup.git synced 2025-12-17 15:36:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

add create-release-note slash command and documentation

Browse Source
This commit is contained in:
George Liu 2025-10-17 00:38:04 +10:00
parent c90188251f
commit 94724c9c51
2 changed files with 541 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

534
.claude/commands/documentation/create-release-note.md Normal file
View File

@ -0,0 +1,534 @@
# 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:
```text
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
```bash
/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
```bash
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:
```text
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:
```bash
# 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:
```text
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
```markdown
## 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
```markdown
## 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
```text
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
```markdown
## 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

7
README.md
View File

@ -130,6 +130,13 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st
- Matches existing README style and tone - Matches existing README style and tone
- Usage: `/create-readme-section "Create an installation section for my Python project"` - Usage: `/create-readme-section "Create an installation section for my Python project"`
- **`/create-release-note`** - Generate comprehensive release documentation from recent commits with dual output formats
- Interactive workflow with two modes: by commit count or by commit hash range (last 24/48/72 hours)
- Produces customer-facing release note (value-focused, no technical jargon) and technical engineering note (SHA references, file paths)
- Comprehensive commit analysis with grouping by subsystem and traceability to specific SHAs
- Supports direct arguments for quick generation or interactive selection for precise control
- Usage: `/create-release-note` (interactive), `/create-release-note 20` (last 20 commits), or select commit hash after viewing recent commits
### `/security` Commands ### `/security` Commands
- **`/security-audit`** - Perform comprehensive security audit of the codebase - **`/security-audit`** - Perform comprehensive security audit of the codebase