jankneumann/changelog-version

Changelog & Version

Generate changelog entries from git history and suggest semantic version bumps based on conventional commit types.

Arguments

$ARGUMENTS - Optional flags:

• --since <ref> (git ref or tag to start from; default: last changelog update or all commits)
• --bump (apply the suggested version bump to VERSION and CHANGELOG.md)
• --dry-run (show what would change without modifying files; default when no flags given)
• --format <keep-a-changelog|simple> (changelog format; default: keep-a-changelog)

Prerequisites

• Python 3.12+
• Git repository with conventional commit messages (type(scope): message)
• VERSION file in project root (created automatically if missing)
• CHANGELOG.md in project root (created automatically if missing)

Local CLI Mutation Boundary

Default analysis and --dry-run are read-only. Any invocation that applies a version bump or writes VERSION / CHANGELOG.md MUST first enter a managed worktree in local CLI execution:

CHANGE_ID="changelog-version-<version-or-date>"
eval "$(python3 "<skill-base-dir>/../worktree/scripts/worktree.py" setup "$CHANGE_ID")"
cd "$WORKTREE_PATH"
skills/.venv/bin/python skills/shared/checkout_policy.py require-mutation

Version Bump Rules

The script analyzes commits since the last version tag or changelog entry and suggests a bump level:

| Commit Prefix | SemVer Impact | Examples | |---------------|---------------|----------| | feat | MINOR bump | New skill, new capability, new API endpoint | | fix | PATCH bump | Bug fixes, corrections | | docs | PATCH bump | Documentation-only changes | | refactor | PATCH bump | Code restructuring without behavior change | | chore | PATCH bump | Maintenance, dependency updates, archiving | | test | PATCH bump | Test additions or fixes | | perf | PATCH bump | Performance improvements | | BREAKING CHANGE | MAJOR bump | Footer or ! after type signals breaking change |

The highest-impact commit determines the suggestion. For example, if there are 5 fix commits and 1 feat commit, the suggestion is MINOR.

Steps

1. Analyze Git History

Run the changelog analysis script to scan commits and categorize changes:

python3 <agent-skills-dir>/changelog-version/scripts/changelog.py analyze \
  --repo-root <project-root> \
  --since <ref-or-tag>

This outputs:

• Categorized commit list (Added, Changed, Fixed, etc.)
• Suggested version bump level (MAJOR, MINOR, or PATCH)
• Current version from VERSION file
• Proposed next version

2. Review Suggestions

Present the analysis to the user:

1. Current version from VERSION
2. Suggested bump with rationale (which commits drive the suggestion)
3. Changelog preview in Keep a Changelog format
4. Key commits that influence the version decision

Ask the user to confirm or override the suggested bump level before applying.

3. Apply Changes (if --bump or user confirms)

python3 <agent-skills-dir>/changelog-version/scripts/changelog.py apply \
  --repo-root <project-root> \
  --bump <major|minor|patch> \
  --date <YYYY-MM-DD>

This will:

1. Update VERSION with the new version number
2. Move [Unreleased] entries in CHANGELOG.md under a new version heading
3. Add a fresh [Unreleased] section

4. Commit Version Bump

After applying, commit both files:

git add VERSION CHANGELOG.md
git commit -m "chore(release): bump version to <new-version>"

5. Integration with Feature Workflow

This skill is designed to be invoked:

• After /implement-feature — to preview what version bump the new feature warrants
• Before /cleanup-feature — to include the changelog entry in the merge PR
• Standalone — for periodic changelog updates or release preparation

When invoked after implementing a feature, the script automatically detects the OpenSpec change-id from the branch name and highlights commits related to that change.