# Zircote Documentation Review Changelog

> Changelog Management

- Skill: `tomevault-io/zircote-documentation-review-changelog` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/zircote-documentation-review-changelog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/zircote-documentation-review-changelog/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/zircote-documentation-review-changelog

---


# Changelog Management

Changelogs are the primary way users understand what changed between versions. A good changelog builds trust, reduces support tickets, and makes upgrade decisions easier. This skill covers the full lifecycle: format, generation, automation, and maintenance.

## Critical: Comparison Links

Every version entry in a Keep a Changelog file requires a comparison link at the bottom of the file. This is the most commonly forgotten element and breaks the linkability that makes changelogs useful. Always include them:

```markdown
[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0
```

When adding a new version entry, update both the new version's link AND the `[Unreleased]` link to point to the new tag.

## Changelog Overview

The recommended approach combines **Keep a Changelog** format with **semantic-release** for automation. This pairing works because Keep a Changelog is human-readable and widely recognized, while semantic-release eliminates manual version management:

- **Automatic Generation**: Changelog generated from git commits via conventional commit messages
- **Version Bumping**: Automatic semver versioning based on commit types (feat → minor, fix → patch)
- **Release Notes**: GitHub releases populated automatically
- **Breaking Changes**: Highlighted prominently with migration guidance
- **Categorized Changes**: Features, fixes, and other changes grouped logically

## Changelog Format

### Keep a Changelog Format

The project follows [Keep a Changelog](https://keepachangelog.com/) format:

```markdown
# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New feature description

### Changed
- Change description

### Deprecated
- Deprecated feature notice

### Removed
- Removed feature notice

### Fixed
- Bug fix description

### Security
- Security fix description

## [1.2.0] - 2024-01-15

### Added
- Add blog post generation with Gemini AI
- Add social media integration (Discord, LinkedIn, Telegram, Twitter)

### Changed
- Update Next.js to v16
- Migrate to Cache Components mode

### Fixed
- Fix database connection timeout issue
- Fix chart rendering on mobile devices

## [1.1.0] - 2024-01-01

### Added
- Add COE bidding results endpoint
- Add interactive charts with Recharts

### Fixed
- Fix pagination in car makes endpoint

## [1.0.0] - 2023-12-15

### Added
- Initial release
- Car registration data API
- Next.js web application
- PostgreSQL database with Drizzle ORM
- Redis caching
- SST v3 infrastructure

[Unreleased]: https://github.com/username/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/username/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/username/repo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/username/repo/releases/tag/v1.0.0
```

## Semantic Release Configuration

### .releaserc.json

The release rules below separate user-visible changes (feat, fix, perf, revert → trigger releases) from internal changes (docs, style, chore, refactor, test, build, ci → no release). This prevents version noise from changes that don't affect consumers.

```json
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git"
  ],
  "preset": "conventionalcommits",
  "releaseRules": [
    { "type": "feat", "release": "minor" },
    { "type": "fix", "release": "patch" },
    { "type": "perf", "release": "patch" },
    { "type": "revert", "release": "patch" },
    { "type": "docs", "release": false },
    { "type": "style", "release": false },
    { "type": "chore", "release": false },
    { "type": "refactor", "release": false },
    { "type": "test", "release": false },
    { "type": "build", "release": false },
    { "type": "ci", "release": false }
  ],
  "parserOpts": {
    "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES"]
  }
}
```

## Automated Changelog Generation

### GitHub Actions

```yaml
# .github/workflows/release.yml
name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - run: pnpm install

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release
```

## Manual Changelog Updates

### Adding Unreleased Changes

Add entries under the `[Unreleased]` section as work is merged. This keeps the changelog current without waiting for release time.

### Creating a New Release Entry

```markdown
## [1.3.0] - 2024-02-01

### Added
- Add user authentication
- Add admin panel

### Changed
- Upgrade Next.js to v16.1.0
- Update database schema

### Fixed
- Fix memory leak in cache
- Fix broken links in documentation

### Security
- Update vulnerable dependencies
```

## Commit Types and Changelog Sections

| Commit Type | Changelog Section | Version Bump |
|-------------|------------------|--------------|
| `feat:` | Added | Minor (0.x.0) |
| `fix:` | Fixed | Patch (0.0.x) |
| `perf:` | Performance | Patch |
| `refactor:` | Changed | None |
| `docs:` | Documentation | None |
| `style:` | Changed | None |
| `test:` | None | None |
| `chore:` | None | None |
| `build:` | None | None |
| `ci:` | None | None |
| `revert:` | Fixed | Patch |
| `BREAKING CHANGE` | Breaking Changes | Major (x.0.0) |

## Example Changelog Entries

### Feature Addition

```markdown
## [1.2.0] - 2024-01-15

### Added
- **Blog Generation**: Automatically generate blog posts from car registration data using Google Gemini AI
  - Configurable prompts for different content styles
  - Automatic SEO optimization
  - Support for custom topics
- **Social Media Integration**: Post updates to Discord, LinkedIn, Telegram, and Twitter
  - Automated posting when new data is available
  - Customizable message templates
  - Rate limiting support
```

### Bug Fix

```markdown
### Fixed
- **Database**: Fix connection timeout issue when processing large datasets
  - Increased connection pool size
  - Added connection retry logic
  - Improved error handling
- **Charts**: Fix chart rendering on mobile devices
  - Updated responsive breakpoints
  - Fixed touch event handling
  - Improved performance on low-end devices
```

### Breaking Change

```markdown
## [2.0.0] - 2024-03-01

### BREAKING CHANGES

- **API**: Changed authentication method from API keys to JWT tokens
  - Migration guide: https://docs.sgcarstrends.com/migration/v2
  - API keys deprecated and will be removed in v2.1.0
  - Update clients to use new authentication flow

- **Database**: Renamed `cars` table to `vehicle_registrations`
  - Run migration: `pnpm db:migrate`
  - Update queries to use new table name
  - Backward compatibility maintained until v2.1.0

### Added
- New authentication system with JWT tokens
- Support for refresh tokens
```

## Changelog Best Practices

The goal is entries that help users decide whether to upgrade and what to watch out for. Vague entries ("fixed bugs") are worse than no entries — they signal carelessness.

### 1. Clear Descriptions
Write for users, not developers. Include what changed and why it matters:
- Good: "Add rate limiting to API endpoints (100 req/min per IP)"
- Bad: "Added stuff"

### 2. Group Related Changes
Keep all features under Added, all fixes under Fixed. Don't interleave types.

### 3. Include Context
For significant changes, add sub-bullets with impact, root cause, or performance data. Users making upgrade decisions need this context.

### 4. Link to Issues/PRs
Reference the PR or issue number for traceability: `([#123](url))`

## Viewing and Validating

### Quick Commands
```bash
# Preview without releasing
npx semantic-release --dry-run

# Lint CHANGELOG.md format
pnpm markdownlint CHANGELOG.md
```

For detailed generation commands, validation scripts, and local viewing tips, see `references/semantic-release-config.md`.

## Migration Guide Template

When creating breaking changes, include a migration guide:

```markdown
## [2.0.0] - 2024-03-01

### BREAKING CHANGES

#### Authentication Method Changed

**What changed:**
- API authentication now uses JWT tokens instead of API keys

**Migration steps:**

1. **Update client code** to use new authentication:
   ```javascript
   // Before
   headers: { 'X-API-Key': 'your-key' }

   // After
   headers: { 'Authorization': 'Bearer your-jwt-token' }
   \```

2. **Obtain JWT token** from new `/auth/login` endpoint:
   ```bash
   curl -X POST https://api.sgcarstrends.com/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"username":"user","password":"pass"}'
   \```

3. **Update environment variables**:
   ```bash
   # Remove
   API_KEY=your-old-key

   # Add
   JWT_SECRET=your-jwt-secret
   \```

**Timeline:**
- API keys supported until: **April 1, 2024**
- Must migrate by: **March 31, 2024**

**Support:**
- Questions: [GitHub Discussions](https://github.com/username/repo/discussions)
- Issues: [GitHub Issues](https://github.com/username/repo/issues)
```

## Troubleshooting

### Semantic Release Not Generating Changelog
Common causes: no conventional commits since last release, wrong branch, or missing GITHUB_TOKEN. Check `git log --oneline` to verify commit format and `git branch` to verify you're on the release branch.

### Duplicate Entries
Clean up manually, then commit: `git commit -m "docs: remove duplicate changelog entries"`

## Additional Resources

### Reference Files

For detailed guidance, consult:
- **`references/semantic-release-config.md`** - Advanced semantic-release configuration patterns
- **`references/conventional-commits-mapping.md`** - Mapping from commit types to changelog sections

### Example Files

Working examples in `examples/`:
- **`sample-changelog.md`** - Complete changelog following Keep a Changelog format

### External References

- Keep a Changelog: https://keepachangelog.com
- Semantic Versioning: https://semver.org
- Semantic Release: https://semantic-release.gitbook.io
- Conventional Commits: https://www.conventionalcommits.org
- Related files:
  - `CHANGELOG.md` - Project changelog
  - `.releaserc.json` - Semantic release config
  - Root CLAUDE.md - Release process

## Summary

Automate generation with semantic-release, write clear user-focused entries, group by change type, highlight breaking changes prominently with migration guides, and link to issues/PRs for traceability.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/zircote) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->