kbrdn1/dotfiles/changelog-generator

Changelog Generator

CLI Go tool + skill for generating and managing changelogs from git history.

When to Use

• "generate the changelog for version X.Y.Z"
• "split the changelog into individual files"
• "extract the git log"
• "calculate working days for this release"
• "prepare changelog for the release"

Architecture

~/.claude/skills/changelog-generator/
├── cmd/changelog-generator/main.go    # CLI entry point
├── internal/
│   ├── parser/parser.go               # CHANGELOG.md + git log parsing
│   ├── splitter/splitter.go           # split into individual version files
│   └── calendar/calendar.go           # working days (FR holidays, course weeks)
├── config/changelog.config.json       # default exclusions config
├── templates/generate_changelog.md    # prompt template for redaction
└── scripts/setup.sh                   # build + install

Setup (one time)

cd ~/.claude/skills/changelog-generator
bash scripts/setup.sh

Or build manually:

cd ~/.claude/skills/changelog-generator
go build -o bin/changelog-generator ./cmd/changelog-generator

Subcommands

extract -- git log to file

Extracts git history between two branches into git-log.txt using a structured format parsable by the tool.

changelog-generator extract --base main --compare dev --limit 400

Output: <project-root>/git-log.txt

split -- CHANGELOG.md to individual files

Parses CHANGELOG.md and generates one file per version in changelogs/:

• Release versions: changelogs/vX.Y.Z.md
• Pre-releases (major 0 or -beta/-rc suffix): changelogs/pre-releases/vX.Y.Z.md

Uses SHA-256 hash comparison to only write files that actually changed. Reports created/updated/unchanged counts.

changelog-generator split --output-dir ./changelogs --clean

Flags:

• --changelog: path to main CHANGELOG.md (default: CHANGELOG.md)
• --output-dir: output directory (default: ./changelogs)
• --clean: remove orphaned files not present in CHANGELOG.md

metrics -- working days calculation

Calculates development productivity metrics per version:

• calendar days, working days (excluding weekends, French holidays, course weeks)
• unique days with commits, commits per day efficiency
• outputs JSON report

changelog-generator metrics --changelog CHANGELOG.md

Configuration via changelog.config.json:

{
  "country": "FR",
  "course_weeks": [
    {"start": "2025-01-20", "end": "2025-01-24"},
    {"start": "2025-02-17", "end": "2025-02-21"}
  ]
}

French holidays are calculated automatically (11 fixed + 3 Easter-dependent via computus algorithm).

generate -- full pipeline

Runs extract + prompts for redaction + split in sequence.

changelog-generator generate --version v1.2.0 --base main --compare dev

Steps:

1. Extract git log from base..compare
2. Print instructions for changelog redaction (via /generate_changelog Claude command or manual edit)
3. Split existing CHANGELOG.md into individual files

Workflow

The recommended workflow for a new release:

1. changelog-generator extract --base main --compare dev
   -> generates git-log.txt
 
2. /generate_changelog   (Claude command using templates/generate_changelog.md)
   -> Claude reads CHANGELOG.md + git-log.txt and appends the new version
 
3. changelog-generator split --output-dir ./changelogs --clean
   -> splits into changelogs/vX.Y.Z.md files
 
4. (optional) changelog-generator metrics
   -> generates working_days_report.json

Or use make targets if the project has them:

make generate-git-log       # step 1
make generate-changelogs    # step 3
make calculate-working-days # step 4

CHANGELOG.md Format

The parser supports two header formats:

• # Version X.Y.Z - YYYY-MM-DD (Flippad convention)
• ## [X.Y.Z] - YYYY-MM-DD (Keep a Changelog standard)

Entry format:

-**Feat** : #<issue> ([#<pr>](url)) Description
  > Detailed description with technical context
  > DD/MM/YYYY - @author

Entries are auto-categorized into Features, Fixes, and Chores based on bold level markers (**Feat**, **Fix**, **Chore**, etc.) or inferred from keywords.

Pre-release Detection

A version is considered pre-release when:

• Major version is 0 (e.g. 0.42.0) -- semver convention
• Version has a pre-release suffix: -alpha, -beta, -rc.1, -dev

This replaces the previous hardcoded logic (major == "0" && minor == "23").

Improvements Over Original Tools

Error Handling

Boundaries

Will: extract git logs, parse changelogs, split into files, calculate working days, provide prompt for redaction

Will not: automatically write changelog content (that's the human/AI redaction step), push to git, create releases, interact with GitHub API