gh-bradleyboehmke-brads-marketplace-document-generator/commands/generate-changelog.md

description

description
Create a new CHANGELOG.md file from scratch for a project

Generate Changelog

Objective

Create a new CHANGELOG.md file following standards (Keep a Changelog format) with entries inferred from git history, supporting both semantic and calendar versioning.

Activated Skills

1. changelog-standards (document-generator) - changelog format and structure
2. version-validation (document-generator) - Versioning rules and validation
3. git-history-analysis (document-generator) - Git commit parsing patterns

Parameters

• --version-type (optional): semantic (default) or calendar
• --format (optional): single-file (default, CHANGELOG.md) or yearly (docs/changelog/YYYY.md)
• --style (optional): standard (default, Keep a Changelog) or detailed (Highlights + Technical Details)
• --path (optional): Custom changelog location (e.g., docs/CHANGELOG.md, CHANGELOG.md)
• --initial-version (optional): Starting version (default: 0.1.0 for semantic, YYYY.1 for calendar)
• --tier (optional): Prototype, MVP, Production

Process

1. Pre-flight Checks

Determine changelog location:

• If --path specified: Use that location
• If --format=yearly: Use docs/changelog/YYYY.md
• Otherwise: Use CHANGELOG.md (default)

Check if changelog already exists at target location.

If exists:

⚠️  CHANGELOG.md already exists

What would you like to do?
1. Skip - keep existing changelog
2. Backup and regenerate
3. Use /document-generator:update-changelog instead

2. Detect Version Type

Auto-detect from git tags, pyproject.toml, or package.json:

• Versions matching YYYY.N pattern → CalVer
• Versions matching X.Y.Z pattern → SemVer
• --version-type parameter → Override
• Default → SemVer

3. Analyze Git History

Retrieve all commits from initial commit to HEAD:

git log --no-merges --pretty=format:"%h|%s|%ad" --date=short

Parse commit messages (conventional commits or keyword-based), filter noise, categorize into sections, group related commits, and rephrase in user-facing language.

Extract PR/issue numbers: Look for (#123), #123, or PR references in commit messages to link entries to GitHub.

4. Determine Initial Version

If --initial-version specified: Use that

Otherwise:

• SemVer: Start with 0.1.0 (pre-release) or 1.0.0 (if mature)
• CalVer: Use current year and .1 (e.g., 2025.1)

Ask user if unclear:

What initial version should I use?
1. 0.1.0 (pre-release/prototype)
2. 1.0.0 (stable first release)
3. Custom version

5. Generate CHANGELOG.md

Choose format based on --style parameter:

Standard style (default):

## [VERSION] - YYYY-MM-DD [TIER]

### Added
- Feature description (#PR)

### Changed
- Change description (#PR)

### Fixed
- Bug fix (#PR)

Detailed style:

## [VERSION] - YYYY-MM-DD [TIER]

### Highlights
- Major feature or improvement (executive summary)
- Critical fix or update

### Detailed Notes

#### Added
- Feature description with technical context (#PR)
  - Sub-detail 1
  - Sub-detail 2

#### Changed
- Change description with rationale (#PR)

#### Fixed
- Bug fix with context (#PR)

Include PR/issue links where available from commit messages.

6. Write File

Write to determined location:

• --path specified: Write to custom path
• --format=yearly: Create docs/changelog/ if needed, write to docs/changelog/YYYY.md
• Default: Write to CHANGELOG.md in project root

Create parent directories if they don't exist.

7. Provide Guidance

✓ Created CHANGELOG.md with initial version VERSION

File location: [path]
Version type: [SemVer/CalVer]
Tier: [tier if specified]

Next steps:
1. Review generated entries for accuracy
2. Add any missing user-facing changes
3. Commit the changelog: git add CHANGELOG.md
4. Tag the release: git tag vVERSION
5. Use /document-generator:update-changelog for future updates

Output Format

Console (default): Display summary and next steps

Markdown (if --output specified): Save changelog as markdown file

Constraints

• Token budget: Keep command concise, delegate to skills
• One changelog per project (single source of truth)
• Focus on user-facing changes only
• No speculation - use actual git history
• Validate version format using version-validation skill

Examples

Basic usage:

/document-generator:generate-changelog
→ Creates CHANGELOG.md with SemVer, starting at 0.1.0

Calendar versioning:

/document-generator:generate-changelog --version-type=calendar
→ Creates CHANGELOG.md with CalVer (2025.1)

With tier annotation:

/document-generator:generate-changelog --initial-version=1.0.0 --tier=MVP
→ Creates CHANGELOG.md starting at [1.0.0] [MVP]

Yearly format:

/document-generator:generate-changelog --format=yearly
→ Creates docs/changelog/2025.md

Custom location:

/document-generator:generate-changelog --path=docs/CHANGELOG.md
→ Creates docs/CHANGELOG.md

Detailed style with highlights:

/document-generator:generate-changelog --style=detailed
→ Creates CHANGELOG.md with Highlights + Detailed Notes sections