changelog-update

Changelog Update Skill

Automates the CHANGELOG.md maintenance cycle for Forge Space repos (and any project following Keep a Changelog format).

Scope note (2026-07-23): in release-please repos (the default), release-please owns changelog promotion, version bump, and tag via its release PR — do not run the promote flow there. This skill remains for repos without release-please configured, and /pr-to-release still uses its append-only mode for [Unreleased] entries in those repos.

When to Use

• Cutting a new release (patch, minor, or major)
• [Unreleased] has accumulated significant work
• CHANGELOG is stale relative to git tags
• After merging a batch of PRs that should be versioned together

Workflow

Step 1 — Gather context

# Current state
REPO=$(git remote get-url origin | sed 's/.*github.com[:/]\(.*\)\.git/\1/')
CURRENT_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || echo "unknown")
LATEST_TAG=$(git tag --sort=-version:refname | head -1)
UNRELEASED_COMMITS=$(git log ${LATEST_TAG}..main --oneline | wc -l | tr -d ' ')

echo "Package version: $CURRENT_VERSION"
echo "Latest tag:      $LATEST_TAG"
echo "Commits since:   $UNRELEASED_COMMITS"

# Check [Unreleased] section size
grep -c "^-\s" CHANGELOG.md && echo "bullet points in CHANGELOG"

# Check version alignment
head -5 CHANGELOG.md

Step 2 — Determine version bump type

Based on the commits since the last tag:

• feat: or feat!: present → minor (or major if breaking)
• Only fix:, chore:, docs:, test:, refactor: → patch
• BREAKING CHANGE in body or ! after type → major

# Auto-detect bump type from commits
git log ${LATEST_TAG}..main --format="%s" | python3 -c "
import sys, re
msgs = sys.stdin.readlines()
breaking = any('!' in m.split(':')[0] or 'BREAKING' in m for m in msgs)
has_feat = any(re.match(r'^feat[\(!:]', m) for m in msgs)
print('major' if breaking else 'minor' if has_feat else 'patch')
"

Step 3 — Compute new version