zhongwei/gh-mtr-marketplace-changelog-manager

Fork 0

Files

Zhongwei Li ec5c049ea6 Initial commit

2025-11-30 08:41:36 +08:00

19 KiB

Raw Permalink Blame History

description, aliases

description

aliases

Initialize CHANGELOG.md and RELEASE_NOTES.md for a new project or retroactively from git history

cl-init

changelog-init

Initialize changelog documentation for a project by analyzing entire git history and generating both developer and user-facing documentation files.

Usage

/changelog-init                    # Interactive initialization
/changelog-init --from-beginning  # Analyze entire git history
/changelog-init --from-tag v1.0.0 # Start from specific version
/changelog-init --empty           # Create empty template files

# Historical Replay Mode (NEW)
/changelog-init --replay           # Interactive period-based replay
/changelog-init --replay --period monthly    # Monthly period grouping
/changelog-init --replay --period weekly     # Weekly period grouping
/changelog-init --replay --period by-release # Group by releases
/changelog-init --replay --period auto       # Auto-detect best period

Workflow

Step 1: Project Analysis

Detects existing version files (package.json, setup.py, etc.)
Identifies versioning scheme in use
Analyzes git tag patterns
Detects commit message conventions

Step 2: History Processing

Extracts all commits from starting point
Groups by releases (if tags exist)
Categorizes changes
Identifies key milestones

Step 3: File Generation

Creates CHANGELOG.md with complete history
Creates RELEASE_NOTES.md with major highlights
Generates .changelog.yaml configuration
Sets up .changelog-metadata.json for tracking

Replay Workflow (Historical Period-Based Generation)

The --replay mode generates changelogs by "replaying" history through time periods (daily/weekly/monthly/by-release), creating changelog entries as if they were updated in real-time during development.

Phase 1: Period Detection

Agent: period-detector (Claude Haiku)

🔍 Analyzing repository structure...

Repository: user/awesome-project
First commit: 2023-03-15 (619 days ago)
Total commits: 523
Contributors: 24
Git tags: 12 releases detected

Auto-detecting optimal period strategy...
✅ Recommended: weekly (21.4 commits/week average)

Period options:
1. Weekly (74 periods, ~7 commits/period)
2. Monthly (20 periods, ~26 commits/period)
3. By-Release (12 periods, ~44 commits/period)
4. Auto (use recommended: weekly)

Select period strategy [1-4] or press Enter for auto: _

Detection Logic:

Analyzes commit frequency and distribution
Detects existing release tags
Calculates project age and activity patterns
Provides smart recommendations with rationale

Phase 2: Boundary Calculation

Agent: period-detector (Claude Haiku)

📅 Calculating period boundaries...

Strategy: Weekly (Monday-Sunday)
Total periods: 74
Empty periods (will be skipped): 8
Merge-only periods (will be skipped): 3
Active periods to analyze: 63

Period boundaries:
- Week 1:  2023-03-13 to 2023-03-19 (15 commits)
- Week 2:  2023-03-20 to 2023-03-26 (22 commits)
- Week 3:  2023-03-27 to 2023-04-02 (18 commits)
...
- Week 74: 2025-11-10 to 2025-11-16 (8 commits) [Unreleased]

First period note: Week 1 has 287 commits (initial development)
→ Will use summary mode for clarity

Continue with analysis? [Y/n]: _

Boundary Features:

Calendar-aligned periods (weeks start Monday, months are calendar months)
Automatic skip of empty periods
Automatic skip of merge-only periods
First-period summarization for large initial development
Partial final period handling (→ [Unreleased])

Phase 3: Parallel Period Analysis

Agent: period-coordinator (Claude Sonnet)

⚙️ Orchestrating multi-period analysis...

Execution plan:
- Total periods: 63
- Concurrent workers: 3
- Estimated time: ~4 minutes
- Cache enabled: Yes

Batch 1/21: Analyzing periods 1-3 in parallel...
 ✅ Week 1 (2023-03-13): 287 commits → Summarized
 ✅ Week 2 (2023-03-20): 22 commits → 18 changes categorized
 ✅ Week 3 (2023-03-27): 18 commits → 15 changes categorized

Batch 2/21: Analyzing periods 4-6 in parallel...
 ✅ Week 4 (2023-04-03): 25 commits → 20 changes categorized
 ⚠️ Week 5 (2023-04-10): Analysis timeout, retrying...
 ✅ Week 5 (2023-04-10): 31 commits → 28 changes categorized
 ✅ Week 6 (2023-04-17): 19 commits → 16 changes categorized

[Progress: 9/63 periods complete - 14% - ETA 3m 42s]
...

Per-Period Analysis: Each period invokes:

git-history-analyzer (Sonnet): Extract and group commits for period
commit-analyst (Haiku): Batch-analyze unclear commits (invoked automatically by git-history-analyzer)
Caching: Results cached per period for instant regeneration

Phase 4: Changelog Synthesis

Agent: changelog-synthesizer (Claude Sonnet)

📝 Generating hybrid-format changelog...

Format: Hybrid (version releases with period subsections)
Structure:
- [Unreleased] section: 2 active periods
- Released versions: 12 versions across 61 periods
- Total entries: 412 changes categorized

Generating CHANGELOG.md...
✅ 63 period sections created
✅ 12 version sections created
✅ Navigation TOC added (74 periods)
✅ 412 changes formatted

Generating RELEASE_NOTES.md...
✅ Period-aware user-facing notes created
✅ Adapted tone for end-users
✅ Highlighted major features per period

Output Format:

CHANGELOG.md: Hybrid format with version sections containing period subsections
RELEASE_NOTES.md: User-friendly with period-based highlights
Navigation: Table of contents for changelogs >10 periods

Phase 5: Verification and Commit

✅ Changelog generation complete!

Files created:
- CHANGELOG.md (1,847 lines, 63 period sections)
- RELEASE_NOTES.md (423 lines, user-friendly format)
- .changelog.yaml (configuration persisted)
- .changelog-cache/ (63 period analyses cached)

Preview of CHANGELOG.md:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Changelog

## [Unreleased]

### Week of November 11, 2025
#### Added
- Real-time notification system (#256)

### Week of November 4, 2025
#### Added
- Advanced search filters (#252)

## [2.1.0] - 2024-10-27

### Week of October 21, 2024
#### Added
- REST API v2 with pagination (#234)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Actions:
1. Review generated files? [Y/n]
2. Commit to git? [Y/n]
3. Create version tag? [y/N]

Agent Orchestration

CRITICAL: You MUST use the Task tool to invoke these agents in the correct sequence.

Standard Mode Agent Sequence

For standard /changelog-init (non-replay):

1. Project Context Extractor (Claude Haiku)

Use Task tool with:
- subagent_type: "changelog-manager:project-context-extractor"
- description: "Extract project context from documentation"
- prompt: "Analyze CLAUDE.md, README.md, and docs/ to extract project context for user-focused release notes."

2. Git History Analyzer (Claude Sonnet)

Use Task tool with:
- subagent_type: "changelog-manager:git-history-analyzer"
- description: "Analyze entire git history"
- prompt: "Extract all commits from beginning (or specified tag), group by releases/PRs/features, categorize changes, and detect breaking changes."

3. GitHub Matcher (Claude Sonnet) - OPTIONAL

Only invoke if GitHub integration enabled.

Use Task tool with:
- subagent_type: "changelog-manager:github-matcher"
- description: "Match commits to GitHub artifacts"
- prompt: "Enrich all historical commits with GitHub references."

4. Changelog Synthesizer (Claude Sonnet)

Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Generate initial changelog files"
- prompt: "Generate complete CHANGELOG.md and RELEASE_NOTES.md from entire project history using project context for user focus."

Replay Mode Agent Sequence

For /changelog-init --replay (period-based historical generation):

1. Project Context Extractor (Claude Haiku)

Same as standard mode.

2. Period Detector (Claude Haiku)

Use Task tool with:
- subagent_type: "changelog-manager:period-detector"
- description: "Detect optimal period strategy"
- prompt: "Analyze repository history to detect optimal period strategy (daily/weekly/monthly/by-release), calculate period boundaries, and present options to user."

Purpose: Analyzes commit frequency, project age, and release patterns to recommend optimal period grouping strategy.

Output: Period boundaries with start/end commits and dates for each period.

3. Period Coordinator (Claude Sonnet)

Use Task tool with:
- subagent_type: "changelog-manager:period-coordinator"
- description: "Orchestrate multi-period analysis"
- prompt: "Coordinate parallel analysis of all periods by invoking git-history-analyzer for each period, managing cache, and handling retries."

Purpose: Orchestrates parallel analysis of all time periods, invoking git-history-analyzer once per period with period context.

Sub-invocations (managed by period-coordinator):

For each period: Invokes git-history-analyzer with period boundaries
Optional: Invokes github-matcher to enrich period commits
Caches results per period for fast regeneration

4. Changelog Synthesizer (Claude Sonnet)

Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Generate hybrid-format changelogs"
- prompt: "Generate hybrid-format CHANGELOG.md (versions with period subsections) and period-aware RELEASE_NOTES.md from multi-period analysis."

Purpose: Synthesizes period-based analysis into hybrid changelog format with version sections containing period subsections.

Integration Flow

Standard Mode:

project-context-extractor (Haiku)
         ↓
git-history-analyzer (Sonnet)
         ↓
github-matcher (Sonnet) [OPTIONAL]
         ↓
changelog-synthesizer (Sonnet)
         ↓
    Write files

Replay Mode:

project-context-extractor (Haiku)
         ↓
period-detector (Haiku)
         ↓
period-coordinator (Sonnet)
    ↓
    └─→ [For each period in parallel]
         git-history-analyzer (Sonnet)
         github-matcher (Sonnet) [OPTIONAL]
         ↓
changelog-synthesizer (Sonnet)
         ↓
    Write files

Options

Standard Mode

--from-beginning: Analyze entire repository history
--from-tag <tag>: Start from specific git tag
--empty: Create template files without historical content
--config-only: Only generate .changelog.yaml configuration
--force: Overwrite existing files (backup created)

Replay Mode (NEW)

--replay: Enable historical replay mode with period-based generation
--period <strategy>: Period grouping strategy
- daily: One entry per day with commits
- weekly: One entry per week (Monday-Sunday)
- monthly: One entry per calendar month
- quarterly: One entry per quarter (Q1, Q2, Q3, Q4)
- annual: One entry per year
- by-release: One entry per git tag/release
- auto: Auto-detect best strategy (default)
--calendar-align: Align periods to calendar boundaries (default: true)
--skip-empty: Skip periods with no commits (default: true)
--skip-merge-only: Skip periods with only merge commits (default: true)
--max-workers <n>: Concurrent period analyses (default: 3, max: 5)
--no-cache: Disable caching (slower but always fresh)
--hybrid-format: Generate hybrid format CHANGELOG.md (default: true)
--replay-in-release-notes: Apply replay structure to RELEASE_NOTES.md (default: true)

Examples

New Project Setup

You: /changelog-init --empty

Claude: 📝 Initializing changelog files...

Created:
✅ CHANGELOG.md (template)
✅ RELEASE_NOTES.md (template)
✅ .changelog.yaml (configuration)

Your changelog files are ready! Next steps:
1. Customize .changelog.yaml for your project
2. Run `/changelog update` after making changes
3. Run `/changelog release` when ready to publish

Retroactive Generation

You: /changelog-init --from-beginning

Claude: 📊 Analyzing repository history...

Found:
- 523 commits
- 12 tagged releases
- 24 contributors
- First commit: 2023-03-15

Generating comprehensive changelog...

✅ Generated CHANGELOG.md with 12 versions
✅ Generated RELEASE_NOTES.md with major milestones
✅ Created configuration files

Notable milestones detected:
- v1.0.0: Initial release
- v2.0.0: Major rewrite with breaking changes
- v2.5.0: Performance optimizations

Replay Mode: Auto-Detection

You: /changelog-init --replay

Claude: 🔍 Analyzing repository for replay...

Repository analysis:
- Total commits: 523
- First commit: 2023-03-15 (619 days ago)
- Releases: 12 tagged versions
- Contributors: 24
- Commit frequency: 21.4 commits/week

Auto-detection results:
✅ Recommended strategy: weekly
   Rationale: Consistent activity (15-30 commits/week)

Alternative strategies:
- Monthly: 20 periods, ~26 commits/period
- By-Release: 12 periods, ~44 commits/period

Use recommended strategy? [Y/n]: Y

📅 Calculating 74 weekly periods...
- Active periods: 63
- Empty periods (skipped): 8
- Merge-only periods (skipped): 3

Proceed with analysis? [Y/n]: Y

⚙️ Executing parallel analysis (3 workers)...
[Progress bar] 63/63 periods analyzed - 100% - 3m 42s elapsed

✅ Generated CHANGELOG.md (1,847 lines, hybrid format)
✅ Generated RELEASE_NOTES.md (423 lines, period-aware)
✅ Configuration saved to .changelog.yaml
✅ Cache created: .changelog-cache/ (63 period analyses)

Replay Mode: Monthly Periods

You: /changelog-init --replay --period monthly

Claude: 📅 Generating changelog with monthly periods...

Period breakdown:
- March 2023: 45 commits
- April 2023: 67 commits
- May 2023: 52 commits
...
- November 2025: 23 commits (partial, → [Unreleased])

Total: 20 active months, 3 empty months (skipped)

Analyzing in parallel (3 workers)...
✅ Complete! Generated hybrid CHANGELOG.md with 20 month sections.

Replay Mode: Release-Based

You: /changelog-init --replay --period by-release

Claude: 🏷️ Grouping history by releases...

Detected releases:
- v0.1.0 (2023-03-15): 15 commits
- v0.2.0 (2023-04-12): 28 commits
- v1.0.0 (2023-06-01): 67 commits (major release)
- v1.1.0 (2023-07-15): 34 commits
...
- v2.5.0 (2024-10-27): 42 commits
- Unreleased: 23 commits

Total: 12 releases + unreleased section

Analyzing releases...
✅ Generated CHANGELOG.md with 13 sections (12 releases + unreleased)

Replay Mode: High-Activity Project (Daily)

You: /changelog-init --replay --period daily

Claude: ⚠️ Daily period strategy selected

Repository has 523 commits over 619 days
This will create ~619 daily periods

Recommendation: Weekly or monthly might be more readable
Continue with daily strategy? [y/N]: y

📅 Calculating daily periods...
- Active days: 287
- Empty days (skipped): 332

Proceed? This may take ~8 minutes [Y/n]: Y

⚙️ Analyzing 287 daily periods (3 workers)...
[Progress: 287/287 - 100% - 7m 53s]

✅ Generated CHANGELOG.md (3,421 lines)
⚠️ Note: Changelog is very large. Consider using weekly strategy.

Replay Mode: Custom Configuration

You: /changelog-init --replay --period weekly --max-workers 5 --hybrid-format

Claude: 📋 Replay configuration:
- Period: Weekly (Monday-Sunday)
- Workers: 5 concurrent analyses
- Format: Hybrid (versions + periods)
- Cache: Enabled
- Skip empty: Yes
- Skip merge-only: Yes

⚙️ Executing with 5 concurrent workers...
[Faster execution with more parallelism]

✅ Complete in 2m 18s (vs estimated 4m with 3 workers)

Replay Mode: Regenerate Specific Period

You: /changelog-init --replay-period "2024-Q3" --force

Claude: 🔄 Regenerating specific period...

Period: Q3 2024 (July-September)
- Original analysis: 2025-01-15
- Commits in period: 87
- Previous entries: 64 changes

Regenerating with current configuration...
✅ Period regenerated
✅ Updated CHANGELOG.md (merged new analysis)
✅ Backup created: CHANGELOG.2025-11-14.md.backup

Generated Files

CHANGELOG.md Template

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Initial project setup

### Changed

### Deprecated

### Removed

### Fixed

### Security

Configuration File

# .changelog.yaml
changelog:
  conventional_commits: true
  include_authors: true
  include_commit_hash: false
  categories:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security

release_notes:
  audience: "end-users"
  tone: "professional"
  use_emoji: true

versioning:
  strategy: "semver"
  auto_bump:
    breaking: "major"
    features: "minor"
    fixes: "patch"

replay:
  enabled: false
  default_strategy: "auto"
  performance:
    enable_parallel: true
    max_concurrent_periods: 3
    enable_cache: true

Hybrid Format CHANGELOG.md (Replay Mode)

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Table of Contents

- **2025**
  - [Week of November 11](#week-of-november-11-2025) - Unreleased
  - [Week of November 4](#week-of-november-4-2025) - Unreleased
  - [Week of October 21](#week-of-october-21-2024) - v2.1.0
  - [Week of October 14](#week-of-october-14-2024) - v2.1.0
- **2024**
  - [Month of September](#month-of-september-2024) - v2.0.0
  ...

## [Unreleased]

### Week of November 11, 2025

#### Added
- Real-time notification system with WebSocket support (#256, @dev2)
  - Automatic reconnection with exponential backoff
  - Event types: entity.created, entity.updated, entity.deleted

#### Fixed
- Memory leak in background job processor (#258, @dev1)

### Week of November 4, 2025

#### Added
- Advanced search filters with fuzzy matching (#252, @dev3)

## [2.1.0] - 2024-10-27

### Week of October 21, 2024

#### Added
- REST API v2 with cursor-based pagination (#234, @dev1)
  - Backward compatible with v1 using version headers
  - See migration guide in docs/api/v2-migration.md

#### Changed
- **BREAKING:** Authentication now uses JWT tokens instead of server sessions
  - Sessions will be invalidated upon upgrade
  - Update client libraries to v2.x for compatibility

### Week of October 14, 2024

#### Fixed
- Race condition in concurrent file uploads (#245, @dev2)
  - Implemented proper file locking mechanism

#### Security
- Updated dependencies to address CVE-2024-1234 (High severity)

## [2.0.0] - 2024-09-30

### Month of September 2024

#### Added
- Complete UI redesign with modern component library (#210, @design-team)
- Dark mode support across all views (#215, @dev4)

#### Changed
- Migrated from Webpack to Vite
  - Development server startup reduced from 30s to 3s
  - Bundle size reduced by 22%

#### Removed
- Legacy XML export format (use JSON or CSV)
- Python 3.7 support (minimum version now 3.8)

[Unreleased]: https://github.com/user/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/user/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/user/repo/releases/tag/v2.0.0

Integration

This command works with:

/changelog update - Add new changes
/changelog release - Prepare releases
Git hooks - Automate updates

19 KiB Raw Permalink Blame History

changelog-init

Usage

Workflow

Step 1: Project Analysis

Step 2: History Processing

Step 3: File Generation

Replay Workflow (Historical Period-Based Generation)

Phase 1: Period Detection

Phase 2: Boundary Calculation

Phase 3: Parallel Period Analysis

Phase 4: Changelog Synthesis

Phase 5: Verification and Commit

Agent Orchestration

Standard Mode Agent Sequence

1. Project Context Extractor (Claude Haiku)

2. Git History Analyzer (Claude Sonnet)

3. GitHub Matcher (Claude Sonnet) - OPTIONAL

4. Changelog Synthesizer (Claude Sonnet)

Replay Mode Agent Sequence

1. Project Context Extractor (Claude Haiku)

2. Period Detector (Claude Haiku)

3. Period Coordinator (Claude Sonnet)

4. Changelog Synthesizer (Claude Sonnet)

Integration Flow

Options

Standard Mode

Replay Mode (NEW)

Examples

New Project Setup

Retroactive Generation

Replay Mode: Auto-Detection

Replay Mode: Monthly Periods

Replay Mode: Release-Based

Replay Mode: High-Activity Project (Daily)

Replay Mode: Custom Configuration

Replay Mode: Regenerate Specific Period

Generated Files

CHANGELOG.md Template

Configuration File

Hybrid Format CHANGELOG.md (Replay Mode)

Integration

19 KiB

Raw Permalink Blame History