Changelog Writer

Changelog Writer

Overview

This skill provides comprehensive expertise in writing changelogs and release notes that effectively communicate software changes to their intended audiences. It covers the Keep a Changelog standard, semantic versioning alignment, conventional commit conventions, automation tooling, migration guides for breaking changes, deprecation communication, and strategies for writing to different audience levels (developers, end users, stakeholders).

Keep a Changelog Format

Standard Template

# Changelog

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

The format is based on [Keep a Changelog]([reference URL]),
and this project adheres to [Semantic Versioning]([reference URL]).

## [Unreleased]

### Added
- Support for batch product imports via CSV upload

### Fixed
- Cart total calculation rounding error for currencies with 3 decimal places

## [2.3.0] - 2025-01-15

### Added
- Full-text search endpoint (`GET /products/search`) with relevance scoring
- `metadata` field on Product resource for arbitrary key-value data
- Idempotency key support on all write endpoints
- Rate limit headers (`X-Rate-Limit-Remaining`, `X-Rate-Limit-Reset`)

### Changed
- Default pagination limit increased from 10 to 20 items per page
- Product image upload now accepts WebP format in addition to JPEG and PNG
- Error responses now include `request_id` field for support reference

### Deprecated
- `GET /products?q=` query parameter. Use `GET /products/search` instead.
  Will be removed in v3.0.0 (scheduled Q3 2025).

### Fixed
- Order creation failing when shipping address contains Unicode characters
- Memory leak in WebSocket connection handler during high traffic
- Incorrect HTTP status code (200 instead of 201) on successful resource creation

### Security
- Upgraded `jsonwebtoken` from 8.5.1 to 9.0.0 to address CVE-2022-23529
- API keys are now hashed in database (previously stored in plaintext)

## [2.2.1] - 2024-12-20

### Fixed
- Critical: Database connection pool exhaustion under sustained load
- Webhook retry logic not respecting exponential backoff

## [2.2.0] - 2024-12-01

### Added
- Webhook support for order status changes
- Product category hierarchy (nested categories up to 5 levels)

### Changed
- Minimum Node.js version raised from 16 to 18

[Unreleased]: [reference URL]
[2.3.0]: [reference URL]
[2.2.1]: [reference URL]
[2.2.0]: [reference URL]

Change Categories

Rules for Good Changelog Entries

Writing Changelog Entries:
├── Start with a verb (Added, Fixed, Changed, Removed)
├── Describe the user impact, not the code change
│   ├── GOOD: "Fixed cart total rounding error for JPY currency"
│   ├── BAD: "Fixed floating point arithmetic in calculateTotal()"
├── Be specific but concise (one line per change)
├── Group related changes together
├── Include issue/PR references for traceability
│   └── "Fixed memory leak in WebSocket handler (#423)"
├── Order by importance within each category
├── Include context for non-obvious changes
│   └── "Changed: Increased rate limit from 100 to 200 req/min
│         (based on usage analysis showing legitimate users were throttled)"
└── Never include internal-only changes
    ├── Skip: "Refactored helper functions"
    ├── Skip: "Updated CI pipeline"
    └── Skip: "Fixed typo in internal docs"

Semantic Versioning

Version Number Decision Tree

Determining the Next Version Number:

Current version: X.Y.Z

Did you make backward-incompatible API changes?
├── YES → Bump MAJOR: (X+1).0.0
│   Examples:
│   ├── Removed an endpoint or field
│   ├── Changed the type of an existing field
│   ├── Renamed an existing field or parameter
│   ├── Changed error response format
│   └── Dropped support for a platform/runtime
│
├── NO → Did you add new functionality in a backward-compatible way?
│   ├── YES → Bump MINOR: X.(Y+1).0
│   │   Examples:
│   │   ├── New endpoint added
│   │   ├── New optional parameter added
│   │   ├── New optional response field added
│   │   └── New configuration option added
│   │
│   └── NO → Did you fix bugs or make internal changes?
│       └── YES → Bump PATCH: X.Y.(Z+1)
│           Examples:
│           ├── Bug fix
│           ├── Performance improvement
│           ├── Documentation correction
│           └── Security patch

Pre-release versions:
├── Alpha: 1.0.0-alpha.1 (unstable, incomplete features)
├── Beta: 1.0.0-beta.1 (feature-complete, may have bugs)
├── RC: 1.0.0-rc.1 (release candidate, should be stable)

Conventional Commits

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types and Changelog Mapping

Examples

feat(auth): add OAuth2 PKCE flow support

Implement the Authorization Code with PKCE flow for public clients
(mobile apps, SPAs) as recommended by OAuth 2.1.

Closes #234

---

fix(orders): correct tax calculation for Canadian provinces

GST/HST was being applied at the federal rate for all provinces.
Now correctly uses province-specific rates.

Fixes #567

---

feat(api)!: change product ID format from integer to UUID

BREAKING CHANGE: All product IDs in API responses are now UUIDs.
Requests using integer IDs will receive a 400 error.
See migration guide: [reference URL]

Automated Changelog Generation

Tool Comparison

release-please Configuration

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v4
        with:
          release-type: node
          changelog-types: |
            [
              {"type": "feat", "section": "Features", "hidden": false},
              {"type": "fix", "section": "Bug Fixes", "hidden": false},
              {"type": "perf", "section": "Performance", "hidden": false},
              {"type": "deps", "section": "Dependencies", "hidden": false}
            ]

Changeset-Based Workflow (Monorepo)

<!-- .changeset/add-search-endpoint.md -->
---
"@myorg/api": minor
"@myorg/sdk-js": minor
---

Added full-text search endpoint (`GET /products/search`) with relevance
scoring. The JavaScript SDK now includes a `client.products.search()` method.

# Developer workflow
npx changeset                 # Interactive: select packages, bump type, description
git add .changeset/*.md
git commit -m "docs: add changeset for search feature"
git push

# Release workflow (CI)
npx changeset version         # Updates CHANGELOG.md and package.json versions
npx changeset publish         # Publishes to npm and creates git tags

Migration Guides

Migration Guide Template

# Migration Guide: v2 to v3

## Overview

Version 3.0 introduces a new authentication system, updates the product ID
format, and removes several deprecated endpoints. This guide walks through
each breaking change and provides step-by-step migration instructions.

**Estimated migration time**: 2-4 hours for most integrations.

## Prerequisites

- Update the SDK to v3.x: `install @example/sdk@^3.0.0 via npm`
- Ensure your application handles the new error response format

## Breaking Changes

### 1. Product IDs changed from integer to UUID

**Before (v2):**
```json
{ "id": 12345, "name": "Widget" }

After (v3):

{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Widget" }

Migration steps:

1. Update your database schema: ALTER TABLE products ALTER COLUMN external_id TYPE uuid;
2. Update API response parsing to handle string IDs
3. A mapping endpoint is available during the transition period: GET /v3/products/id-mapping?legacy_id=12345
4. The mapping endpoint will be available until 2025-12-31

2. Authentication moved to OAuth 2.0

Before (v2):

HTTP client request -H "X-API-Key: sk_test_EXAMPLE_KEY_REPLACE_ME" [reference URL]

After (v3):

# Step 1: Get token
TOKEN=$(HTTP client request -s -X POST [reference URL] \
  -d "grant_type=client_credentials&client_id=xxx&client_secret=yyy" \
  | jq -r '.access_token')

# Step 2: Use token
HTTP client request -H "Authorization: Bearer $TOKEN" [reference URL]

Migration steps:

1. Generate OAuth2 credentials in the dashboard
2. Implement token refresh logic (tokens expire after 1 hour)
3. Legacy API keys will continue to work until 2025-06-30

Deprecation Removal

The following deprecated features have been removed in v3:

Rollback Plan

If you encounter issues after migrating:

1. The v2 API remains available at `[reference URL] until 2025-12-31
2. Pin your SDK to v2: install @example/sdk@^2.0.0 via npm
3. Contact support@example.com for migration assistance

## Deprecation Notices

### Deprecation Communication Timeline

Deprecation Lifecycle: ├── T-6 months: Announce deprecation │ ├── Changelog entry under "Deprecated" │ ├── API response header: Deprecation: true │ ├── Documentation banner on deprecated features │ ├── Email notification to API key owners │ └── Blog post for major deprecations ├── T-3 months: Warning intensification │ ├── API response header: Sunset: │ ├── Console warnings in SDK │ └── Dashboard notification ├── T-1 month: Final notice │ ├── Email reminder to remaining users │ └── Dashboard alert ├── T-0: Removal │ ├── Feature removed │ ├── Requests return 410 Gone with migration link │ └── Changelog entry under "Removed" └── T+3 months: Cleanup └── Remove 410 handler, return 404

### Deprecation Header Standards

HTTP Response Headers for Deprecated Endpoints:

Deprecation: true Sunset: Sat, 01 Jul 2025 00:00:00 GMT Link: <[reference URL]>; rel="successor-version"

## Audience-Specific Release Notes

### Developer-Facing (Changelog)

```markdown
## [2.3.0] - 2025-01-15

### Added
- `GET /products/search` endpoint with full-text search and relevance scoring
- `metadata` JSONB field on Product resource
- Idempotency-Key header support on POST, PUT, PATCH endpoints

### Fixed
- Order creation returns 500 when shipping address contains emoji (#423)

End-User-Facing (App Release Notes)

## What's New in Version 2.3

**Better Search**: Find products faster with our improved search. Results
are now ranked by relevance, so the best matches appear first.

**Bug Fixes**: Fixed an issue where orders could fail if your address
contained special characters. Various stability improvements.

Stakeholder-Facing (Executive Summary)

## Release 2.3 Summary - January 2025

**Key Improvements:**
- New search functionality expected to improve product discovery by 15-20%
- Security: API keys now encrypted at rest (SOC2 compliance requirement)
- Performance: Average API response time reduced from 180ms to 120ms

**Metrics Impact:**
- Enables A/B testing of search results
- Reduces support tickets related to order failures (~50 tickets/month)

**No downtime required for deployment.**

Production Checklist

• Changelog follows Keep a Changelog format
• Version number follows semantic versioning rules
• All user-facing changes are documented
• Breaking changes are clearly labeled and explained
• Migration guide provided for all breaking changes
• Deprecated features have sunset dates
• Compare links at bottom of CHANGELOG.md are correct
• Release notes written for target audience (developer/user/stakeholder)
• Conventional commits used consistently
• Automated changelog generation configured in CI
• Deprecation notices sent to affected users
• Internal-only changes excluded from public changelog
• Security fixes reference CVE numbers where applicable

When to Use

Use this skill when:

• Designing or implementing changelog writer solutions
• Reviewing or improving existing changelog writer approaches
• Making architectural or implementation decisions about changelog writer
• Learning changelog writer patterns and best practices
• Troubleshooting changelog writer-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# Changelog Writer Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement changelog writer for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended changelog writer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When changelog writer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities