changelog-writer

name	changelog-writer
description	Expert changelog and release notes covering Keep a Changelog format, semantic versioning, conventional commits, automated changelog generation, migration guides, deprecation notices, breaking change communication, and audience-appropriate language. Use when the user asks about changelog writer, changelog writer best practices, or needs guidance on changelog writer implementation. Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"technical-writing documentation version-control","category":"writing","subcategory":"technical-writing","depends":"","disclaimer":"none","difficulty":"intermediate"}

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

Category	Meaning	Example
Added	New features	New API endpoint, new CLI command
Changed	Changes to existing functionality	Default value change, behavior modification
Deprecated	Features marked for future removal	Old API version, legacy parameter
Removed	Features removed in this release	Deleted endpoint, dropped platform support
Fixed	Bug fixes	Corrected calculation, resolved crash
Security	Security-related changes	Vulnerability patches, auth improvements

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

Commit Type	Changelog Section	Version Bump
feat:	Added	MINOR
fix:	Fixed	PATCH
perf:	Changed (performance)	PATCH
docs:	(not in changelog)	None
style:	(not in changelog)	None
refactor:	(not in changelog)	None
test:	(not in changelog)	None
chore:	(not in changelog)	None
ci:	(not in changelog)	None
Any type with ! or BREAKING CHANGE:	Breaking Changes	MAJOR

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

Tool	Language	Features
conventional-changelog	Node.js	Git log → CHANGELOG.md
release-please	Node.js	GitHub Action, auto PR for releases
semantic-release	Node.js	Full automation: version, changelog, publish
changesets	Node.js	Monorepo support, manual changeset files
git-cliff	Rust	Configurable, fast, template-based
towncrier	Python	Fragment-based, manual review

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:

Feature	Deprecated In	Alternative
GET /v2/products?q=	v2.3.0	GET /v3/products/search
X-API-Key auth	v2.5.0	OAuth 2.0 Bearer token
product.category (string)	v2.1.0	product.category_id (UUID)

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 [e-mail] 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