Changelog

Changelog — Changelog & Release Notes

Activate When

• User invokes /godmode:changelog
• User says "update changelog", "write release notes", "what changed?"
• User says "generate migration guide", "breaking change documentation"
• User says "set up conventional commits", "auto-generate changelog"
• Preparing a release (often chained from /godmode:release or /godmode:ship)
• Recent commits introduced breaking changes that need communication
• Team publishes a new version to a package registry

Workflow

Step 1: Analyze Change History

Examine commits, PRs, and tags since the last release:

CHANGE ANALYSIS:
  Last release: <tag> (<date>)

Commands to gather data:

# Commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Step 2: Conventional Commits Setup

If not already configured, set up Conventional Commits for automatic changelog generation:

Commit Message Format

<type>(<scope>)!: <description>

[optional body]

Types:

CONVENTIONAL COMMIT TYPES:
| Type | Description | Changelog? |

Commitlint Setup

# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

Step 3: Keep a Changelog Format

Generate or update CHANGELOG.md following the Keep a Changelog standard:

# Changelog

This file documents all notable changes to this project.

Keep a Changelog Rules

CHANGELOG RULES:
1. Changelogs are for humans, not machines
2. Include an entry for every version

Step 4: Auto-Generate Changelog

Use tools to generate changelog from Conventional Commits:

conventional-changelog

# Install
npm install --save-dev conventional-changelog-cli

standard-version / release-please

# Option A: standard-version (local tool)
npm install --save-dev standard-version

# .github/workflows/release-please.yml
name: Release Please
on:

Step 5: Release Notes for Different Audiences

Write release notes tailored to who reads them:

Developer-Facing Release Notes

# v2.0.0 Release Notes

## Breaking Changes

After (v2.0):

const client = createClient({
  baseUrl: 'https://api.example.com',
  apiKey: 'my-api-key',

Migration: See Migration Guide below.

Minimum Node.js version raised to 20

Node.js 18 is no longer supported. Node.js 20 LTS is now the minimum.

New Features

Automatic request retries (#234)

Failed requests are now automatically retried with exponential backoff. Configure via the retries option (default: 3).

const client = createClient({ retries: 5, retryDelay: 1000 });

Streaming responses (#256)

New client.stream() method for Server-Sent Events:

for await (const event of client.stream('/events')) {
  console.log(event.data);
}

Bug Fixes

• Fixed memory leak in connection pool when requests timeout (#278)
• Fixed race condition in concurrent batch requests (#291)
• Fixed incorrect Content-Type header for multipart uploads (#303)

Performance

• Reduced cold start time by 40% through lazy initialization (#312)
• Improved JSON parsing performance for large payloads (#318)

Dependencies

• Upgraded undici to 6.x (HTTP client)
• Removed node-fetch dependency (replaced by native fetch)

#### User-Facing Release Notes
```markdown

Release Notes Template

RELEASE NOTES STRUCTURE:

For developers:

Step 6: Breaking Change Communication

When breaking changes are introduced, communicate them thoroughly:

BREAKING CHANGE COMMUNICATION PLAN:

1. ADVANCE NOTICE (1-2 releases before)

Step 7: Migration Guide Generation

Create detailed migration guides for breaking changes:

# Migration Guide: v1.x to v2.0

## Overview

2. Update client initialization

Find all occurrences of:

createClient(url, apiKey)

Replace with:

createClient({ baseUrl: url, apiKey })

Automated: Run the codemod:

npx @<package>/codemods v2-client-init

3. Update deprecated method calls

4. Update TypeScript types

// Before
import { ClientOptions } from '<package>';

5. Test your changes

npm test

Common Issues

"TypeError: createClient is not a function"

Check if a named import is used instead of default import:

// Wrong
import { createClient } from '<package>';

"Error: Node.js 18 is not supported"

Update to Node.js 20: nvm install 20 && nvm use 20

Rollback

If you need to rollback:

npm install <package>@1

Getting Help

• GitHub Issues
• Discord

Step 8: Commit and Transition

1. If setting up Conventional Commits:
   Commit: "changelog: configure conventional commits and commitlint"

2. If generating changelog:
   Commit: "changelog: generate CHANGELOG.md for v<version>"

3. If writing release notes:
   Commit: "changelog: write release notes for v<version>"

4. If creating migration guide:
   Commit: "changelog: add migration guide for v<old> to v<new>"

5. Transition:
   - If preparing release: "Changelog ready. Proceed with /godmode:ship to publish."
   - If migration needed: "Migration guide created. Share with users before releasing."

Key Behaviors

IF breaking changes > 0: write migration guide before release. WHEN commits don't follow conventional format: parse PR titles as fallback. IF changelog entry count < commit count * 0.5: review for missed changes.

Quality Targets

• Target: 100% PRs tagged with changelog category
• Generation time: <5min for release notes
• Target: 0 breaking changes without BREAKING CHANGE tag

HARD RULES

1. NEVER STOP until all commits since last release are categorized and the changelog entry is written.
2. git commit BEFORE verify — commit the changelog/release notes, then verify formatting.
3. Automatic revert on regression — if the generated changelog has incorrect version numbers or dates, revert and regenerate.
4. TSV logging — log every changelog generation run:

   timestamp    version    commits_analyzed    entries_generated    breaking_changes    status
   

5. NEVER include internal-only changes (refactor, test, chore, ci) in user-facing changelogs.
6. NEVER backdate release entries — use the actual publication date.
7. ALWAYS link PRs/issues — every entry must have a reference.

Explicit Loop Protocol

When processing commits for changelog generation:

current_iteration = 0
unprocessed_commits = all commits since last tag
changelog_entries = []

Output Format

After each changelog skill invocation, emit a structured report:

CHANGELOG REPORT:
| Last release | <tag> (<date>) |

Keep/Discard

KEEP if: improvement verified. DISCARD if: regression or no change. Revert discards immediately.

Stop Conditions

Stop when: target reached, budget exhausted, or >5 consecutive discards.