Changelog Generator

---
name: "Changelog Generator"
description: "Generate professional changelogs from git commits with industry-standard categories. Automatically activates when users request changelog generation with time periods."
version: "1.0.0"
dependencies:
  - "git"
  - "bash"
---

# Changelog Generator

Automatically generates professional changelogs from git commits with intelligent filtering, categorization, and multiple output formats for the Quorum project.

## Description

This skill provides comprehensive changelog generation for Quorum project releases, creating both technical documentation and user-friendly communications. It analyzes git commits, filters for relevant changes, categorizes improvements, and generates polished output in multiple formats.

**Use this skill when the user mentions:**
- Generating changelogs with any time period specification
- Creating release notes or development summaries
- Preparing user communications about new features
- Summarizing changes for stakeholders or beta testers
- Analyzing development progress over specific timeframes

**Automatically triggers on phrases like:**
- "generate changelog" / "generate a changelog"
- "create changelog" / "create a changelog"
- "changelog for the past [X] days"
- "changelog for the last [X] weeks"
- "generate changelog for [time period]"
- "create release notes"
- "summarize recent changes"
- "changelog for [X] days"

**Time period examples that trigger the skill:**
- "generate changelog for the past 30 days"
- "create changelog for last 3 days"
- "changelog for 2 weeks"
- "generate changelog for yesterday"
- "changelog since last month"

## Core Capabilities

### 1. Technical Changelog Generation
- **Script**: `changelog-generator.sh`
- **Audience**: Developers, technical stakeholders
- **Content**: Detailed technical changes with GitHub links
- **Categories**: New Features, Enhancements, Bug Fixes, Localization, Compatibility, Maintenance
- **Format**: Markdown + Text versions with commit references

### 2. User-Friendly Changelog Generation
- **Script**: `changelog-user-friendly.sh`
- **Audience**: End users, beta testers, non-technical stakeholders
- **Content**: Benefit-focused descriptions without technical jargon
- **Categories**: New Features, Enhancements, Bug Fixes, Localization, Compatibility, Maintenance
- **Format**: Engaging copy optimized for user excitement

### 3. Intelligent Commit Analysis
- **Conventional Commit Support**: Leverages consistent emoji + conventional commit format
- **Precise Categorization**: Maps commit types directly to changelog categories
- **Smart Filtering**: Uses configurable patterns to identify user-facing changes
- **Quality Enhancement**: Post-processes output for clarity and engagement

#### Commit Type → Category Mapping
- `✨ feat:` / `feat:` → 🎉 **New Features**
- `🎨 style:` / `🚀 perf:` / `perf:` → ✨ **Enhancements**
- `🐛 fix:` / `fix:` → 🐛 **Bug Fixes**
- `🌐 i18n:` / `i18n:` → 🌐 **Localization**
- `🧹 chore:` / `⚙️ refactor:` → 🔧 **Maintenance** (technical only)
- Platform-specific commits → 📱 **Compatibility**

### 4. Multiple Output Formats
- **Markdown**: For documentation, GitHub releases, and web content
- **Plain Text**: For social media, emails, and messaging platforms
- **Analysis Files**: For review and further processing

## Available Scripts

### Technical Changelog (`changelog-generator.sh`)
```bash
./changelog-generator.sh [DAYS] [BRANCH] [CLAUDE_ENHANCE] [OUTPUT_DIR] [--show]
```

**Parameters:**
- `DAYS`: Number of days to analyze (default: 7)
- `BRANCH`: Git branch to analyze (default: cross-platform)
- `CLAUDE_ENHANCE`: Enable Claude post-processing (default: false)
- `OUTPUT_DIR`: Output directory (default: skill/changelogs/)
- `--show`: Display results immediately

**Example:** `./changelog-generator.sh 14 develop true`

### User-Friendly Changelog (`changelog-user-friendly.sh`)
```bash
./changelog-user-friendly.sh [DAYS] [BRANCH] [CLAUDE_ENHANCE] [OUTPUT_DIR] [--show]
```

**Parameters:**
- `DAYS`: Number of days to analyze (default: 14)
- `BRANCH`: Git branch to analyze (default: cross-platform)
- `CLAUDE_ENHANCE`: Enable Claude enhancement (default: true)
- `OUTPUT_DIR`: Output directory (default: skill/changelogs/)
- `--show`: Display preview

**Example:** `./changelog-user-friendly.sh 30 main true`

### Output Structure

All changelogs are stored within the skill directory:
```
.claude/skills/changelog-generator/
├── changelogs/
│   ├── quorum-changelog_2025-11-16.md
│   ├── quorum-changelog_2025-11-16.txt
│   ├── quorum-changelog-user-friendly_2025-11-16_14-30.md
│   ├── quorum-changelog-user-friendly_2025-11-16_14-30.txt
│   └── commits-analysis_2025-11-16_14-30.txt
└── ...
```

## Configuration Files

### Commit Filters (`filters/`)

**User-Facing Commits** (`user-facing-commits.txt`):
```
✨ feat:
feat:
🐛 fix:
fix:
🎨 style:
style:
🚀 perf:
perf:
Add
Implement
Fix
Improve
Enhance
Update
```

**Exclude Patterns** (`exclude-patterns.txt`):
```
playground
audit
component complexity
primitive
typescript
build
lint
task:
doc:
chore:
refactor:
test:
build:
```

### Templates (`templates/`) - MANDATORY

**IMPORTANT: You MUST read and follow these templates exactly for consistent output.**

Templates define the exact structure, formatting, and layout for each output format. Before generating any changelog:

1. **Read the appropriate template file(s)** for the requested output format
2. **Follow the template structure exactly** - same headers, separators, sections
3. **Use the same formatting conventions** - bullet styles, emoji placement, spacing

| Output Type | Template File | Purpose |
|-------------|---------------|---------|
| User-friendly (Markdown) | `templates/user-friendly-format.md` | Discord, documentation, web |
| User-friendly (Plain text) | `templates/user-friendly-format.txt` | Telegram, email, messaging |
| Technical (Markdown) | `templates/technical-format.md` | GitHub releases, dev docs |
| Social media | `templates/social-media-format.txt` | Twitter, short announcements |

**Template Variables:**
- `{{DATE_RANGE}}` - The date range covered (e.g., "December 11-13, 2025")
- `{{PROJECT_NAME}}` - Project name (Quorum)
- `{{CONTENT}}` - Main changelog content

**Key Formatting Rules from Templates:**
- Use `---` as section separators in Markdown (NOT `━━━` unicode lines)
- Use `---` as section separators in Plain text (NOT `━━━` unicode lines)
- Use `•` for bullet points
- Use subcategory emojis from the reference table in templates
- Include the footer with improvement count and date range
- Include the Quorum links at the bottom

## Instructions

When the user requests changelog generation, follow this workflow:

### Step 1: Determine Changelog Type
Analyze the request to identify:
- **Technical Changelog**: For developers, detailed commit tracking, technical stakeholders
- **User-Friendly Changelog**: For end users, marketing, beta announcements, feature highlights
- **Custom Analysis**: Specific date ranges, branches, or focus areas

### Step 2: Read Templates (MANDATORY)

**Before writing any output, you MUST read the template files:**

```
# For user-friendly changelogs, read BOTH:
templates/user-friendly-format.md   # For markdown output
templates/user-friendly-format.txt  # For plain text output

# For technical changelogs:
templates/technical-format.md
```

This ensures consistent formatting across all changelogs.

### Step 3: Execute Appropriate Script & Generate Output

**For Technical Changelogs:**
1. Run `changelog-generator.sh` with appropriate parameters
2. Review generated output for accuracy
3. Enhance with additional context if needed
4. Save in both markdown and text formats **following template structure**

**For User-Friendly Changelogs:**
1. Run `changelog-user-friendly.sh` to generate commit analysis (or use git log directly)
2. Use the analysis to create engaging, benefit-focused descriptions
3. Apply user-friendly writing guidelines:
   - Focus on user capabilities, not technical details
   - Use active language and exciting tone
   - Keep bullet points concise (under 15 words)
   - Group related changes into single descriptions
4. Generate both markdown and text versions **using the exact template structure**
5. Include project-specific formatting (test links, access instructions)

### Step 4: Apply Enhancement Guidelines

**User-Friendly Enhancement Rules:**

✅ **DO:**
- Focus on what users can accomplish with new features
- Use exciting, active language that motivates testing
- Group multiple technical commits into single user-facing features
- Keep descriptions scannable and concise
- Include practical benefits and improvements

❌ **DON'T:**
- Use technical jargon (refactor, implement, optimize, etc.)
- Mention file paths, code references, or technical debt
- Write obvious statements ("works better now")
- Create long, detailed explanations
- Include internal development processes

**Example Transformations:**

*Multiple commits:*
- "Add pin message functionality to MessageComponent"
- "Implement pin UI component with animations"
- "Add unpin capability and state management"

*Becomes:*
📌 **Pinned Messages & Content Management**
- Pin important messages in channels for easy member access

### Step 5: Quality Assurance

**Technical Changelog Check:**
- All commit links work and point to correct repository
- Categories are properly populated with relevant changes
- Statistics accurately reflect included vs. filtered commits
- Markdown formatting is valid and renders correctly

**User-Friendly Changelog Check:**
- Non-technical users can understand all descriptions
- Each bullet point focuses on user benefits
- Tone is exciting and encourages feature testing
- No technical jargon or implementation details remain
- Categories only appear if they contain relevant content

### Step 6: Output and Delivery

1. **Save files** in the specified output directory
2. **Provide file paths** to the user for easy access
3. **Show preview** if requested with --show flag
4. **Offer additional formats** if needed (social media posts, email content, etc.)

## Example Usage Scenarios

### Scenario 1: Weekly Technical Update
**User Request:** "Generate a technical changelog for the last week"

**Skill Response:**
1. Runs `changelog-generator.sh 7 cross-platform false`
2. Generates technical changelog with categorized commits
3. Provides markdown and text versions
4. Shows summary statistics

### Scenario 2: User-Friendly Release Announcement
**User Request:** "Create a user-friendly changelog for the beta users"

**Skill Response:**
1. Runs `changelog-user-friendly.sh 14 cross-platform true`
2. Analyzes commits and categorizes by user impact
3. Generates engaging descriptions focusing on user benefits
4. Creates both markdown (for documentation) and text (for messaging)
5. Includes project-specific formatting and test links

### Scenario 3: Custom Date Range Analysis
**User Request:** "What changed between September 1st and October 15th?"

**Skill Response:**
1. Calculates appropriate parameters for date range
2. Runs appropriate script with custom parameters
3. Generates comprehensive changelog covering the period
4. Highlights major features and improvements

### Scenario 4: Multi-Format Release Package
**User Request:** "Prepare release materials for version 2.1"

**Skill Response:**
1. Generates technical changelog for developer documentation
2. Creates user-friendly version for announcement
3. Provides text versions for social media and email
4. Suggests additional formats (GitHub release notes, newsletter content)

## Integration with Development Workflow

### Pre-Release Process
1. **Generate technical changelog** for internal review
2. **Create user-friendly version** for public announcement
3. **Review with stakeholders** using generated previews
4. **Finalize content** with any manual adjustments
5. **Deploy across channels** using appropriate formats

### Continuous Documentation
- **Weekly technical summaries** for development team
- **Bi-weekly user updates** for beta testing community
- **Monthly feature highlights** for broader audience
- **Ad-hoc analysis** for specific feature releases

### Quality Standards
- **Accuracy**: All information verified against actual commits
- **Clarity**: Technical content accessible to intended audience
- **Engagement**: User-friendly content motivates feature adoption
- **Consistency**: Formatting and tone align with project standards

## Advanced Features

### Custom Filtering
- Modify `filters/` configuration files for project-specific needs
- Add new commit patterns or exclude additional noise
- Create branch-specific or feature-specific filters

### Template Customization
- Edit `templates/` files to match brand guidelines
- Add project-specific headers, footers, or formatting
- Include custom variables and substitutions

### Multi-Branch Analysis
- Compare changes across multiple branches
- Generate merge-specific changelogs
- Track feature branch progress

### Integration Hooks
- Connect with CI/CD pipelines for automated changelog generation
- Integrate with release management tools
- Export to external documentation systems

This skill transforms the manual, error-prone process of changelog creation into an automated, intelligent system that produces professional documentation while saving significant time and ensuring consistency.