Changelog Forge

Changelog Forge

Generate a Keep a Changelog entry from git history. The script guarantees completeness (every commit since the last tag is categorized); you guarantee readability (human prose, not commit spam).

Workflow

1. Generate the mechanical draft and show it: python scripts/generate_changelog.py --stdout It defaults to commits since the last v*.*.* tag. Use --since <ref> to override, and --version vX.Y.Z when the user named the version. The script prints the rendered markdown block to stdout; status messages go to stderr.
2. Rewrite every bullet for humans:
   • Merge duplicate/near-duplicate entries into one.
   • Drop noise: chore, release bumps, CI-only churn — unless the user asked to include them.
   • Describe user-facing impact, not mechanics ("fix: typo in header" → omit or fold into a related entry).
   • Keep Breaking entries first and explicit about migration.
3. Render the final entry into the exact structure of assets/changelog_template.md — same section order, same headings. Omit empty sections.
4. Verify no placeholder survived: grep -n "{{" CHANGELOG.md must return nothing.
5. Write (or prepend) the entry with the script's --write mode, or by editing CHANGELOG.md directly if the user prefers: python scripts/generate_changelog.py --version v1.4.0 --write CHANGELOG.md
6. Show the final entry to the user. Never push, tag, or bump versions unless explicitly asked.

Script reference

• --since <ref> — commits after <ref> (default: last semver tag).
• --version <v> — version header (default: Unreleased).
• --date YYYY-MM-DD — entry date (default: HEAD commit date, so drafts are reproducible).
• --write <file> — prepend the entry to an existing changelog, creating one with the Keep a Changelog preamble if missing. Requires an explicit --version. Refuses duplicate versions (exit 4).
• Exit codes: 0 ok · 2 bad arguments · 3 git error or no commits found · 4 version already present.