Conventional Commits Changelog Builder Skill

--- name: conventional-commits-changelog-builder description: Turns a git log in Conventional Commits format into a ready-to-paste Keep a Changelog release section - Added, Changed, Deprecated, Removed, Fixed, Security - with scopes, issue and commit links and a breaking-changes block. Flags breaking changes without migration notes, non-conforming and fixup commits, reverts and duplicates, and suggests the next SemVer version. Includes an offline stdlib Python builder with --self-test. --- # Conventional Commits Changelog Builder You help maintainers turn the commits since the last tag into a changelog entry people can actually read. Writing it by hand means scrolling a log, guessing which commits matter and forgetting the one breaking change hidden in a footer. Generating it blindly copies every typo, WIP commit and reverted feature into the release. You parse the commits, map them to Keep a Changelog sections, list exactly what was left out and why, and say which version the release should get. ## Files in this skill - `scripts/changelog_build.py` - reads `git log` (default format), `git log --oneline` or a `%x1f`/`%x1e` records export; parses `type(scope)!: description` headers and `BREAKING CHANGE:` footers; groups into Added / Changed / Deprecated / Removed / Fixed / Security with a BREAKING CHANGES block; cancels reverts that are in range, skips merges, drops duplicates, flags fixup/WIP and non-conforming commits with a suggested header; links issues, commits and the compare range; suggests the SemVer bump (0.x aware); can insert the section into an existing CHANGELOG.md (Python 3.8+ standard library only) - `references/commit-to-changelog-mapping.md` - the type -> section table, breaking-change rules, bump rules and the finding codes CC01-CC10 - `references/release-hygiene.md` - writing entries for users, migration notes, what to do with non-conforming history, and CI checks - `templates/release-notes-review.md` - the review to hand back with the section - `examples/git-log.txt` - 21 commits of a fictional CLI (tidyq) since v2.3.1: two breaking changes, a security fix, a deprecation, a revert, a duplicate cherry-pick, a fixup, a WIP and a plain "Fixed ..." commit - `examples/CHANGELOG.md` - the project's existing changelog (Unreleased + 2.3.1 + 2.3.0) - `examples/changelog-report.md` - the real builder output on that log ## Workflow ### 1. Get the commit range Ask for the last released tag and export everything after it, newest first: ``` git log v2.3.1..HEAD > commits.txt git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # safest: keeps bodies, no parsing guesswork ``` Also ask for the current version, the release date, the repository URL (for links), the tag prefix (`v` by default) and whether internal commits (refactor, docs, ci, chore, test) should be listed. A squash-merge workflow is ideal: one PR = one commit = one line. ### 2. Run the builder ``` python3 scripts/changelog_build.py examples/git-log.txt --current 2.3.1 --date 2026-11-03 --repo-url https://github.com/tidyq/tidyq python3 scripts/changelog_build.py commits.txt --current 2.3.1 --insert CHANGELOG.md > CHANGELOG.new.md python3 scripts/changelog_build.py commits.txt --current 0.9.4 --include-internal --json python3 scripts/changelog_build.py --self-test ``` Exit 0 = ready to tag, 1 = high findings, 2 = bad input. Without a shell, apply `references/commit-to-changelog-mapping.md` by hand: parse each header, map type to section, collect `!` and `BREAKING CHANGE:` footers, cancel reverts, then pick the highest bump. ### 3. Fix the findings before tagging - CC03 (high): a `!` commit with no `BREAKING CHANGE:` footer gives users no migration path. Write the note (what breaks, what to do instead) into the section. - CC08 (high): non-conforming commits that look like features or fixes are missing from the changelog. Add them by hand with the suggested header, and turn on a commit-lint check. - CC07: fixup/WIP commits should be squashed before the release; CC04: reverts of older releases need a sentence explaining why. - CC01/CC02/CC05/CC06: wording and conformance; fix in the changelog text, not by rewriting published history. ### 4. Edit for humans The builder gives you correct structure, not good prose. Rewrite entries as user-visible effects ("Export writes Parquet by default" rather than "refactor writer"), merge entries that describe one change, keep scopes that users recognise, and put the BREAKING CHANGES block where nobody can miss it. See `references/release-hygiene.md`. ### 5. Deliver Fill `templates/release-notes-review.md`: version and why, the final section, the migration notes, what was left out, and follow-ups (commitlint, PR title check). With `--insert`, hand back the updated CHANGELOG.md; the original file is never modified. ## Example result On `examples/git-log.txt` (current 2.3.1) the builder reads 21 commits, 85% conforming, and suggests **3.0.0**: `feat(export)!` makes Parquet the default (with a proper BREAKING CHANGE footer) and `fix(config)!` drops the INI config file without any migration note (CC03, high). "Fixed crash when the config file is empty" is not a Conventional Commit and would silently miss the changelog (CC08, high; suggested `fix: crash when the config file is empty`). The token-leak fix lands under Security, the `--legacy-dates` deprecation under Deprecated, the colour-themes feature and its revert cancel out, the cherry-picked BOM fix is listed once, and the merge, fixup, WIP and 5 internal commits are listed as left out. ## Rules - Never invent entries: every line comes from a commit, and every commit is either in the section or in the "left out" list. - A breaking change always gets a migration note and the major bump (minor while on 0.x); never hide it in Changed. - Security fixes go under Security even when the commit type is `fix`. - Do not rewrite published history to fix commit messages; fix the changelog text and add a lint check for the future. - Keep the newest release on top, dates as YYYY-MM-DD and one compare link per version. - The version is a suggestion: the maintainer decides, especially for behaviour changes typed as `fix`.