Conventional Commits Changelog Builder

Conventional Commits Changelog Builder

Turns Conventional Commits history into a Keep a Changelog release section, flagging breaking changes, bad commits and the next version number.

Skill files8 files

references/

templates/

examples/

scripts/

SKILL.md62 lines
1
---
2
name: conventional-commits-changelog-builder
3
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.
4
---
5
6
# Conventional Commits Changelog Builder
7
8
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.
9
10
## Files in this skill
11
12
- `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)
13
- `references/commit-to-changelog-mapping.md` - the type -> section table, breaking-change rules, bump rules and the finding codes CC01-CC10
14
- `references/release-hygiene.md` - writing entries for users, migration notes, what to do with non-conforming history, and CI checks
15
- `templates/release-notes-review.md` - the review to hand back with the section
16
- `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
17
- `examples/CHANGELOG.md` - the project's existing changelog (Unreleased + 2.3.1 + 2.3.0)
18
- `examples/changelog-report.md` - the real builder output on that log
19
20
## Workflow
21
22
### 1. Get the commit range
23
Ask for the last released tag and export everything after it, newest first:
24
```
25
git log v2.3.1..HEAD > commits.txt
26
git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # safest: keeps bodies, no parsing guesswork
27
```
28
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.
29
30
### 2. Run the builder
31
```
32
python3 scripts/changelog_build.py examples/git-log.txt --current 2.3.1 --date 2026-11-03 --repo-url https://github.com/tidyq/tidyq
33
python3 scripts/changelog_build.py commits.txt --current 2.3.1 --insert CHANGELOG.md > CHANGELOG.new.md
34
python3 scripts/changelog_build.py commits.txt --current 0.9.4 --include-internal --json
35
python3 scripts/changelog_build.py --self-test
36
```
37
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.
38
39
### 3. Fix the findings before tagging
40
- 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.
41
- 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.
42
- CC07: fixup/WIP commits should be squashed before the release; CC04: reverts of older releases need a sentence explaining why.
43
- CC01/CC02/CC05/CC06: wording and conformance; fix in the changelog text, not by rewriting published history.
44
45
### 4. Edit for humans
46
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`.
47
48
### 5. Deliver
49
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.
50
51
## Example result
52
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.
53
54
## Rules
55
56
- Never invent entries: every line comes from a commit, and every commit is either in the section or in the "left out" list.
57
- A breaking change always gets a migration note and the major bump (minor while on 0.x); never hide it in Changed.
58
- Security fixes go under Security even when the commit type is `fix`.
59
- Do not rewrite published history to fix commit messages; fix the changelog text and add a lint check for the future.
60
- Keep the newest release on top, dates as YYYY-MM-DD and one compare link per version.
61
- The version is a suggestion: the maintainer decides, especially for behaviour changes typed as `fix`.
62
@OpenSourceBuffGuy

I find openly licensed prompts and post them here.

0 followers · 2,873 prompts

More by @OpenSourceBuffGuy

See all
Ethereum Developer prompt image

Ethereum Developer

Asks the AI to act as an experienced Ethereum developer who writes a Solidity smart contract for an on-chain messenger with public reads and owner-only writes.

act-as, crypto, coding

1 view
Linux Terminal prompt image

Linux Terminal

Makes the AI act as a Linux terminal that replies to each typed command with only its output inside one code block.

simulator, linux, coding

5 views
English Translator and Improver prompt image

English Translator and Improver

Turns the AI into an English translator and editor that detects the input language and returns only an improved, more literary English version.

act-as, translation, rewriting, proofreading

2 views

Reviews

Loading reviews…

Discussion

Loading comments…