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

description

description
Update existing CHANGELOG.md with new entries from recent commits

Update Changelog

Objective

Update existing CHANGELOG.md with new version entries based on recent git commits, maintaining standards and proper version sequencing.

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

• --path (optional): Changelog location (auto-detects if not specified)
• --style (optional): Inherit from existing changelog or specify standard/detailed
• --since (optional): Git ref to start from (default: last version tag or last changelog entry)
• --new-version (optional): Version for new release (auto-increment if not provided)
• --tier (optional): Update tier annotation (Prototype, MVP, Production)
• --draft (optional): Add to [Unreleased] section instead of creating versioned release

Process

1. Locate and Read Changelog

Locate changelog file:

• If --path specified: Use that location
• Otherwise auto-detect from standard locations:
  • CHANGELOG.md (root)
  • docs/CHANGELOG.md
  • docs/changelog/YYYY.md (current year)
  • Search for **/CHANGELOG.md or **/changelog/*.md

If not found:

❌ No CHANGELOG.md found

Run /document-generator:generate-changelog to create one first.

Read and parse existing changelog:

• Extract current version
• Detect version type (SemVer vs CalVer)
• Identify format (single-file vs yearly)
• Detect style (standard vs detailed) from existing structure

2. Determine Commit Range

Find last version:

# From changelog
grep -E "^## \[" CHANGELOG.md | head -n 2 | tail -n 1

# From git tags
git describe --tags --abbrev=0 2>/dev/null

Get commits since last version:

# If last tag exists
git log LAST_TAG..HEAD --no-merges --pretty=format:"%h|%s|%ad" --date=short

# If no tags (first release since changelog creation)
git log --since="$(git log -1 --format=%ai CHANGELOG.md)" --no-merges --pretty=format:"%h|%s|%ad" --date=short

If no new commits:

ℹ️  No new commits since last version

Changelog is up-to-date.

3. Analyze New Commits

Parse commit messages, categorize into sections, filter noise, group related changes, and transform to user-facing language.

Extract PR/issue numbers from commit messages to include as links.

4. Determine New Version

If --new-version specified: Use that (validate with version-validation skill)

If --draft flag: Add to [Unreleased] section

Otherwise, auto-increment:

For SemVer:

• If "feat" or "Added" entries → Increment MINOR (2.1.0 → 2.2.0)
• If only "fix" or "Fixed" entries → Increment PATCH (2.1.0 → 2.1.1)
• If breaking changes detected → Suggest MAJOR (2.1.0 → 3.0.0)

For CalVer (Year.Minor):

• Same year → Increment MINOR (2025.1 → 2025.2)
• New year → Reset to YEAR.1 (2024.5 → 2025.1)

Ask user for confirmation:

Based on commits, I suggest version: [suggested-version]

Changes detected:
- X new features (Added)
- Y bug fixes (Fixed)
- Z improvements (Changed)

What version should I use?
1. [suggested-version] (recommended)
2. Specify custom version
3. Add to [Unreleased] instead

5. Insert New Version Section

Format new entry based on detected or specified style:

Standard style:

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

### Added
- Feature description (#PR)

### Changed
- Improvement description (#PR)

### Fixed
- Bug fix (#PR)

Detailed style:

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

### Highlights
- Major capability added
- Significant improvement made

### Detailed Notes

#### Added
- Feature with technical context (#PR)

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

#### Fixed
- Fix with context (#PR)

Insert location:

• After "## [Unreleased]" section
• Before previous version entries
• Maintain reverse chronological order

Update [Unreleased] section:

• Remove entries that moved to new version
• Keep any remaining draft entries

6. Update Version Comparison Links

At bottom of changelog, add/update links:

[NEW_VERSION]: https://github.com/ORG/REPO/compare/vOLD_VERSION...vNEW_VERSION
[OLD_VERSION]: https://github.com/ORG/REPO/compare/vPREV_VERSION...vOLD_VERSION

Extract repo URL from:

git config --get remote.origin.url

7. Write Updated Changelog

Validate with version-validation skill:

• Version format correct
• Chronological ordering maintained
• No version skips
• Dates are valid

Write updated file back to original location.

8. Provide Guidance

✓ Updated CHANGELOG.md with version NEW_VERSION

Changes:
- Added: X entries
- Changed: Y entries
- Fixed: Z entries

Next steps:
1. Review the new changelog entries
2. Commit changes: git add CHANGELOG.md
3. Tag release: git tag vNEW_VERSION
4. Push with tags: git push --tags

Output Format

Console (default): Display summary and next steps

Markdown (if --output specified): Save updated changelog

Special Cases

Draft Mode (--draft)

Add to [Unreleased] instead of creating versioned release:

## [Unreleased]

### Added
- New feature in development

### Fixed
- Bug fix awaiting release

Use this when:

• Changes not ready for release
• Accumulating changes before version bump
• Working in feature branch

Empty Unreleased Section

If [Unreleased] section exists but is empty, preserve it:

## [Unreleased]

## [1.2.0] - 2025-11-11

Multiple Version Formats

If changelog contains both CalVer and SemVer (migration scenario):

• Detect most recent format
• Warn user about mixed formats
• Suggest standardizing

Examples

Basic usage:

/document-generator:update-changelog
→ Auto-detects last version, suggests next version, updates changelog

With specific version:

/document-generator:update-changelog --new-version=2.1.0
→ Creates version 2.1.0 entry with recent commits

Draft mode:

/document-generator:update-changelog --draft
→ Adds commits to [Unreleased] section

With tier annotation:

/document-generator:update-changelog --new-version=1.0.0 --tier=MVP
→ Creates [1.0.0] [MVP] entry

Since specific ref:

/document-generator:update-changelog --since=v1.5.0
→ Includes all commits since v1.5.0 tag

Custom location:

/document-generator:update-changelog --path=docs/CHANGELOG.md
→ Updates changelog at docs/CHANGELOG.md

Constraints

• Token budget: Keep concise, delegate to skills
• Preserve existing changelog structure
• Maintain chronological order
• Validate all version increments
• No data loss - backup approach recommended