Changelog and Release Notes — Complete Guide

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

Changelogs and release notes communicate API changes to developers by documenting additions, changes, deprecations, and removals with version numbers, release dates, migration guidance, and links to updated documentation so developers can update their integrations confidently.

What You'll Learn

How to structure a changelog, how to categorize changes, how to write clear and actionable changelog entries, how to document deprecations with sunset dates, how to communicate breaking changes, and how to maintain changelogs for multiple API versions.

Why It Matters

Developers depend on your API working the same way every time. When you add, change, or remove features, they need to know exactly what changed and what they need to update in their code. A well-maintained changelog builds trust and reduces support tickets after releases.

Real-World Use

Stripe publishes a detailed changelog with every API release. Each entry lists what changed, why, and how to update your code. DodaTech follows the same pattern for the DodaZIP Compression API, with versioned changelogs and migration guides for breaking changes.

Changelog Structure

flowchart TD
  A[Changelog] --> B[Unreleased]
  A --> C[Version Entries]
  C --> D[Added]
  C --> E[Changed]
  C --> F[Deprecated]
  C --> G[Removed]
  C --> H[Fixed]
  D --> I[New features and endpoints]
  E --> J[Behavior changes]
  F --> K[Features to be removed]
  G --> L[Removed features]
  H --> M[Bug fixes]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Changelog Format

Use the Keep a Changelog format with consistent sections.

# Changelog

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

### Added
- New `compression_level` parameter to `POST /v2/files/compress`
  - Values: `fast` (default), `balanced`, `maximum`
  - Maximum reduces size by 15% more at 2x CPU cost
  - See [compression profiles guide](/docs/compression-profiles)
- Webhook retry mechanism: Failed webhooks now retry up to 3 times
  with exponential backoff. See [webhooks docs](/docs/webhooks)

### Changed
- Increased file size limit from 500 MB to 1 GB for Pro plan
- Rate limit headers now include `X-RateLimit-Remaining` for Pro plan

### Deprecated
- `POST /v1/files/compress` — Use `POST /v2/files/compress` instead
  - Sunset date: 2026-10-01
  - Migration guide: [v1 to v2 migration](/docs/migration-v1-to-v2)
- `compression` parameter on `POST /v2/files/compress`
  - Use `format` parameter instead
  - Sunset date: 2026-09-01

Writing Changelog Entries

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

## 2026-06-15: v2.1.0 — Webhook Improvements

### Added
- Webhook signing with HMAC-SHA256. Verify webhook payloads using
  the signature in the `X-Webhook-Signature` header.
  See [webhook security](/docs/webhooks/security).
  ```python
  from dodatech import Webhook
  if Webhook.verify(payload, signature, secret):
      Process_webhook(payload)

Fixed

• Fixed pagination bug where total field returned incorrect count for filtered queries. This fix changes the total value.
• Webhook delivery now respects Retry-After header from 429 responses

Security

• Deprecated API key v1 format (hex string). New keys use JWT format. Old keys continue to work until 2026-09-15. See migration guide.

## Documenting Breaking Changes

Breaking changes need extra attention. Include migration instructions.

```markdown
## 2026-05-01: v2.0.0 — Breaking Changes

This release includes breaking changes. Please read this carefully
before upgrading.

### BREAKING: Authentication Header Format

**Before (v1.x):**
`Authorization: Token YOUR_API_KEY`

**After (v2.0+):**
`Authorization: Bearer YOUR_API_KEY`

**Migration:** The old format returns HTTP 401 starting in v2.0.
Update all requests to use the Bearer scheme. API keys remain the same.

### BREAKING: Pagination Response Format

**Before:**
```json
{"results": [...], "page": 1, "total": 100}

After:

{"data": [...], "pagination": {"page": 1, "total": 100}}

Migration: Update your response parsers to use data instead of results and pagination.page instead of page.

## Multiple Version Changelogs

For APIs with multiple active versions, maintain separate changelogs.

```markdown
# v1 API Changelog

## 2026-06-01: v1.3.0
- Added deprecation warning headers to all v1 endpoints
- No new features. Maintenance only.

## 2026-04-01: v1.2.0
- Added rate limit headers (backported from v2)
- Bug fix: Fixed timeout on large file uploads

---

# v2 API Changelog

## 2026-07-01: v2.2.0
- Added compression_level parameter
- Increased file size limit to 1 GB

## Automated Changelog Generation

Use tools to generate changelogs from conventional commits.

```bash
# Generate changelog from git history
npx conventional-changelog -p <a href="/frameworks/angular/">Angular</a> -i CHANGELOG.md -s

# Validate changelog format
npx changelog-verify CHANGELOG.md

Common Mistakes

1. No Changelog

Not maintaining a changelog forces developers to discover changes through trial and error or by reading commit messages.

2. Vague Entries

Writing Improved performance or Fixed bugs without specifics. Every entry needs a clear description of what changed and why.

3. No Dates

Changelog entries without dates make it impossible to correlate API changes with integration issues.

4. No Migration Guidance

Documenting breaking changes without migration steps forces developers to figure out upgrades on their own.

5. Mixed Version Formats

Using dates in some entries and semantic versions in others. Choose one format and stick with it.

6. No Unreleased Section

Not maintaining an unreleased changelog section means changes accumulate between releases and the changelog update becomes overwhelming.

7. Hiding Breaking Changes

Burying breaking changes in a long list of minor updates causes developers to miss critical changes that break their integrations.

Practice Questions

1. What are the five standard changelog sections?

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

2. Why include a sunset date for deprecated features?

A sunset date tells developers exactly when the feature will stop working, giving them a deadline for migration. Without a date, developers may delay migration indefinitely.

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

Mark it with BREAKING: prefix, show the old behavior, show the new behavior, and include a migration guide with before and after code examples.

4. Why maintain an Unreleased section in the changelog?

The Unreleased section tracks changes that have been merged but not yet released. When the release happens, the section becomes the release notes without needing to reconstruct the changes.

5. Challenge: Write a changelog for an imaginary API release that includes at least one addition, one change, one deprecation, one removal, and one breaking change with migration instructions.

FAQ

Mini Project: Create a Changelog

Create a changelog for an API with at least 5 releases. Include entries for additions, changes, deprecations, removals, fixes, and at least one breaking change with a migration guide. Use the Keep a Changelog format with proper versioning and dates.

What's Next

Changelogs communicate changes. Now learn to help developers upgrade with Migration Guides. Then explore API Style Guide for consistent Api Design documentation.