changelog-docs-updater

Changelog & Docs Updater

Review git changes and update CHANGELOG.md and project documentation to reflect the latest work.

Workflow

Step 1: Gather Changes

Run these commands to understand the current state:

git log --oneline -20                          # Recent commits
git log --oneline --since="1 week ago"         # Time-based range
git status                                     # Uncommitted changes
git diff --stat                                # Files changed

If the user specifies a range (e.g., "since last tag", "last 5 commits"), use that instead:

# Since last tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)..HEAD

# Specific range
git log --oneline HEAD~5..HEAD

Step 2: Categorize by Conventional Commit Type

Parse each commit message for its prefix and group accordingly:

Commits without a prefix: Classify by reading the diff. If it touches only config/tooling, treat as chore. If it changes behavior, determine if fix or feat fits.

Skip trivial commits: Merge commits, version bumps, "WIP", and typo fixes (unless the user explicitly asks for everything).

Step 3: Update CHANGELOG.md

If CHANGELOG.md exists

1. Read the file
2. Find the ## [Unreleased] section
3. Add new entries under the appropriate ### subheading (create if missing)
4. Preserve existing entries — never overwrite or reorder them
5. Each entry format: - prefix: description (short-hash)

## [Unreleased]

### Features

- feat: add dark mode toggle (a1b2c3d)

### Bug Fixes

- fix: resolve pagination off-by-one error (d4e5f6g)

If CHANGELOG.md does not exist

Create it with this header, then add entries:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

### Features

- feat: description (hash)

Releasing a version

When the user says "release X.Y.Z" or "cut a release":

1. Move all ## [Unreleased] content to ## [X.Y.Z] - YYYY-MM-DD
2. Leave ## [Unreleased] empty with no subsections

Validate formatting

After updating CHANGELOG.md, always run:

npx markdownlint CHANGELOG.md

Fix any errors before proceeding. See Markdownlint Formatting section for common rules.

Step 4: Determine if Docs Need Updates

Scan the changed files to decide which docs to update:

If no relevant docs exist: Skip this step. Don't create docs that don't already exist unless the user asks.

Step 5: Write Doc Updates

For each doc that needs updating:

1. Read the current file to understand its structure
2. Locate the exact section to modify
3. Make targeted edits — don't rewrite sections
4. Preserve existing formatting conventions (heading levels, list style)
5. If you modified a Mermaid diagram, validate it:

   npx @probelabs/maid <file>
   

Step 6: Report Summary

After making changes, report what was done:

## Changes Reviewed

**Commits analyzed:** N (from abc1234 to def5678)
**Date range:** YYYY-MM-DD to YYYY-MM-DD

### Summary by Category
| Category | Count | Key Changes |
|----------|-------|-------------|
| Features | N | feat: ..., feat: ... |
| Bug Fixes | N | fix: ... |

### Files Updated
- `CHANGELOG.md` — Added N entries under [Unreleased]
- `docs/ARCHITECTURE.md` — Updated component hierarchy

Quick Commands

# See what changed recently
git log --oneline -10

# See files touched
git diff --stat HEAD~5..HEAD

# Check if CHANGELOG exists
cat CHANGELOG.md 2>/dev/null | head -5 || echo "No CHANGELOG"

Edge Cases

• No conventional commits: Read the diffs and write meaningful entries yourself. Use chore: for config-only changes.
• CHANGELOG has no [Unreleased]: Add the section at the top (after the header) before adding entries.
• Merge commits: Skip them unless they contain a squashed summary worth documenting.
• Already documented: Compare commit hashes to avoid duplicates.

Markdownlint Formatting

CHANGELOG.md must pass npx markdownlint CHANGELOG.md. Key rules:

MD022 — Blank line after headings: Always add a blank line between a ### Heading and the first list item.

<!-- WRONG -->
### Features
- feat: something

<!-- CORRECT -->
### Features

- feat: something

MD032 — Blank line before lists: Same rule — the blank line after the heading satisfies this.

MD024 — Duplicate headings: CHANGELOG files inherently repeat section names (Features, Bug Fixes) under different dates. Disable this rule in .markdownlint.json:

{
  "no-duplicate-heading": false
}

Validate after every change:

npx markdownlint CHANGELOG.md