Writing Changelogs — Complete Guide

In this tutorial, you will learn about Writing Changelogs. We cover key concepts, practical examples, and best practices to help you master this topic.

Changelogs communicate API changes to developers by documenting every addition, change, deprecation, removal, and fix with version numbers, release dates, clear descriptions of what changed, and Migration instructions when the change affects existing integrations.

What You'll Learn

How to structure a changelog using the Keep a Changelog format, how to categorize changes, how to write clear entry descriptions, how to document deprecations with sunset dates, and how to communicate breaking changes with migration instructions.

Why It Matters

Developers depend on your API working the same way every time. When something changes, they need to know exactly what, why, and what they need to update. A clear, well-maintained changelog builds trust and reduces support tickets after releases.

Real-World Use

Stripe's changelog is the gold standard. Every entry includes what changed, why it changed, and how to update your code. The DodaTech API changelog follows the same format, with categorized entries and migration links for every breaking change.

Changelog Structure

flowchart TD
  A[Changelog] --> B[Unreleased]
  A --> C[Released Versions]
  C --> D[Added]
  C --> E[Changed]
  C --> F[Deprecated]
  C --> G[Removed]
  C --> H[Fixed]
  C --> I[Security]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Changelog Format

Use the Keep a Changelog format with consistent section headers and dates.

## 2026-07-01: v2.2.0 — Compression Profiles

### Added
- New `compression_level` parameter to POST /v2/files/compress
  - Values: `fast` (default), `balanced`, `maximum`
  - Use `maximum` for best compression (15% smaller, 2x slower)
  - See the [compression profiles guide](/docs/compression)

### Changed
- File size limit increased from 500 MB to 1 GB for Pro plan
- Rate limit headers now include `X-RateLimit-Remaining` for all plans

### Deprecated
- `POST /v1/files/compress` — Sunset date: 2026-10-01
  - Migration guide: [/docs/migration-v1-to-v2](/docs/migration-v1-to-v2)

### Fixed
- Job status endpoint now returns correct `ratio` for completed jobs
- Webhook delivery now retries on 5xx responses from your server

Writing Clear Entry Descriptions

Each entry should tell the developer what changed, why, and what action to take.

## 2026-06-15: v2.1.0

### Added
- **Webhook signing verification.** Webhook payloads now include an
  `X-Webhook-Signature` header. Verify payloads using the HMAC-SHA256
  signature to ensure they came from DodaTech.
  [See webhook security docs](/docs/webhooks/security).

### Fixed
- **Rate limit count for list endpoints.** Previously, `GET /v2/files`
  counted as 2 requests. It now correctly counts as 1 request.
  If you were hitting rate limits on list endpoints, you should see
  improved headroom.

Documenting Deprecations

Deprecation entries must include a replacement and a sunset date.

### Deprecated

The following endpoints are deprecated and will be removed according
to the dates below:

| Endpoint | Deprecated In | Sunset Date | Replacement |
|----------|---------------|-------------|-------------|
| POST /v1/compress | v2.0.0 (2026-05-01) | 2026-10-01 | POST /v2/files/compress |
| GET /v1/status | v2.0.0 (2026-05-01) | TBD | GET /v2/jobs/{jobId} |
| compression | v2.1.0 (2026-06-15) | 2026-09-01 | Use format parameter |

Deprecated features continue to work until the sunset date. After that
date, they return HTTP 410 Gone. Migrate before the sunset date.

Breaking Changes

Breaking changes need prominent formatting and migration instructions.

## 2026-05-01: v2.0.0 — Major Release with Breaking Changes

This release includes several breaking changes. Please review the
full [migration guide](/docs/migration-v1-to-v2) before upgrading.

### BREAKING: Authentication Header Format Changed

**Before:** `Authorization: Token YOUR_KEY`
**After:** `Authorization: Bearer YOUR_KEY`

API keys are the same. Only the header format changes. Update all
requests to use the Bearer scheme.

### BREAKING: Pagination Response Restructured

**Before:** `{"results": [...], "page": 1}`
**After:** `{"data": [...], "pagination": {"page": 1}}`

Update response parsers to use `data` instead of `results`.

Maintaining an Unreleased Section

Track changes that have been merged but not yet released.

## Unreleased

### Added
- Support for webhook retries with exponential backoff

### Fixed
- Fixed timeout issue with files over 500 MB (internal tracking: ENG-4521)

---

When releasing, move Unreleased content to a new version entry and
add the release date.

Common Mistakes

1. No Changelog

Not maintaining any changelog. Developers must discover changes through trial and error or by reading commit messages.

2. Vague Entries

Writing Improved performance or Fixed various bugs without specifics. Every entry needs a specific description of what changed.

3. No Dates or Versions

Changelog entries without dates and version numbers make it impossible to correlate changes with issues.

4. No Migration Guidance

Not providing migration instructions for breaking changes forces developers to figure out upgrades independently.

5. Burying Breaking Changes

Listing breaking changes in the middle of minor updates causes developers to miss critical changes.

6. No Deprecation Timeline

Deprecation entries without sunset dates give developers no urgency to migrate.

7. No Unreleased Section

Accumulating changes between releases without tracking them leads to incomplete changelog updates.

Practice Questions

1. What are the standard changelog sections?

Added (new features), Changed (behavior changes), Deprecated (features to be removed), Removed (removed features), Fixed (bug fixes), and Security (vulnerability fixes).

2. What information should every deprecation entry include?

The deprecated feature name, when it was deprecated, the sunset date, and the replacement feature or endpoint with a migration guide link.

3. How do you format a breaking change in a changelog?

Mark it with BREAKING: prefix, show old behavior vs new behavior (before/after), provide migration instructions, and link to the full migration guide.

4. Why maintain an Unreleased section?

The Unreleased section tracks changes made between releases. When you cut a release, you move Unreleased content to a versioned entry without having to reconstruct all the changes.

5. Challenge: Write a changelog for an API that has 3 releases. Include at least one addition, one change, one deprecation, one fix, and one breaking change with migration instructions.

FAQ

Mini Project: Create an API Changelog

Create a changelog for an API with at least 4 releases. Include entries for Added, Changed, Deprecated, Removed, Fixed, and Security categories. Include at least one breaking change with before/after examples and a migration guide link. Use the Keep a Changelog format.

What's Next

Changelogs communicate changes. Now learn to document what changes break existing integrations with Documenting Breaking Changes. Then explore the API Documentation Project.