Proc Changelog

Skill: Changelog Generation

What this skill is

Defines the process for maintaining CHANGELOG.md following the Keep a Changelog standard with Conventional Commits. Use when preparing releases, creating release notes, or documenting changes for users.

CHANGELOG.md format

Keep a Changelog layout, with a worked example of [Unreleased] and two released versions, in format-reference.md.

Conventional Commits → sections mapping

How to generate changelog from git commits

# View commits since the last tag
git log v1.1.0..HEAD --oneline --no-merges

# More detailed format
git log v1.1.0..HEAD \
  --pretty=format:"- %s (%h)" \
  --no-merges \
  | grep -E "^- (feat|fix|perf|refactor|security)"

# View all existing tags
git tag --sort=-version:refname | head -10

Release process — step by step

1. Create section [x.y.z] above [Unreleased]
   └── Move items from [Unreleased] to the new section

2. Filter: include only feat, fix, perf, security
   └── Translate into user-facing language (not technical)

3. Sort within each section: impact → stability → security
   └── Most impactful to the user comes first

4. Review: each line must answer "what can the user do now?"
   └── ❌ "refactors TransactionService to use Strategy pattern"
   └── ✅ "Transaction categorization is now 30% faster"

5. Commit together with the release code
   └── git commit -m "chore(release): v1.2.0 — changelog and version bump"

Semantic versioning (SemVer)

MAJOR / MINOR / PATCH rules and the pre-1.0 caveat are in format-reference.md.

User-oriented writing

❌ Technical (do not include in the public changelog):
"Adds composite index (date, user_id) to the transactions table"
"Refactors GlobalExceptionHandler to use ProblemDetail"

✅ User-oriented:
"Transaction history now loads up to 3x faster"
"Error messages now indicate the specific field with a problem"

Common mistakes

Resources

• format-reference.md — the Keep a Changelog file layout with a worked example, and the SemVer rules.

Reference: Keep a Changelog · SemVer