Changelog and Release Notes — Complete Guide

Changelogs and release notes communicate API changes to developers. Learn how to structure release notes, communicate breaking changes, deprecations, and new features, and maintain versioned documentation.

What You'll Learn

You will learn how to write effective changelogs and release notes for developer portals, how to communicate breaking changes, and how to manage versioned documentation.

Why It Matters

Developers need to know when APIs change, what changed, and whether the change affects their integration. Poor release communication leads to broken integrations, frustrated developers, and support tickets.

Real-World Use

The Durga Antivirus Pro API publishes release notes with every version change. Breaking changes are highlighted with a warning banner, include Migration guides, and provide a 90-day transition period.

flowchart LR
  A[API Change] --> B{Breaking?}
  B -->|Yes| C[Breaking Change Notice]
  B -->|No| D[Minor Change Log]
  C --> E[Deprecation Period]
  E --> F[Migration Guide]
  F --> G[Sunset Date]
  D --> H[Release Notes Entry]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Release Notes Structure

# Threat Intelligence API v2.1.0 Release Notes

**Release date**: 2026-06-28

## New Features

### Batch Threat Query

You can now query up to 100 threats in a single request using the
new `/v1/threats/batch` endpoint.

```bash
curl -X POST "https://api.durgaantivirus.com/v1/threats/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threat_ids": ["thr_001", "thr_002", "thr_003"]}'

Webhook Event Filtering

Webhooks now support event filtering. Use the events parameter when creating webhooks to receive only specific event types.

Improvements

• Reduced latency for threat queries by 40%
• Improved error messages for invalid API keys
• Added request ID to all error responses for debugging

Deprecations

v1 API Endpoints

The following v1 endpoints are deprecated and will be removed on 2026-09-28:

Breaking Changes

Response Format Change

The /v2/threats response format has changed. The data field is now wrapped in a results object.

Old format:

{"data": [{"id": "thr_001"}]}

New format:

{"results": {"data": [{"id": "thr_001"}], "total": 1}}

Migration: Use the v1 to v2 migration guide.

## Versioned Documentation

```yaml
# Version configuration in developer portal
versions:
  current:
    version: "v2.1"
    base_url: "https://api.durgaantivirus.com/v2"
    docs_url: "/api-reference/v2/"
  previous:
    version: "v1.0"
    base_url: "https://api.durgaantivirus.com/v1"
    docs_url: "/api-reference/v1/"
    status: "deprecated"
    sunset: "2026-09-28"

Changelog Automation

# Generate changelog from conventional commits
name: Generate Changelog
on:
  release:
    types: [published]
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate changelog
        uses: heinrichreimer/github-changelog-generator-action@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issues: true
          issuesWoLabels: true
          pullRequests: true
          prWoLabels: true
          unreleased: true

Common Mistakes

1. Burying Breaking Changes in a Long List of Changes

Breaking changes must be the first thing developers see. Separate them from other changes with a clear heading.

2. No Migration Guide

Breaking changes without migration guidance leave developers stuck. Every breaking change needs a migration path.

3. No Sunset Date

Deprecated features need a clear removal date. Without a sunset date, developers do not know when to migrate.

4. Inconsistent Release Schedule

Irregular releases confuse developers. Aim for a consistent release cadence (monthly or quarterly).

5. No Automated Changelog Generation

Manual changelogs are often forgotten. Automate changelog generation from commit messages.

Practice Questions

1. How should breaking changes be communicated to developers?

Breaking changes should be highlighted with a warning banner, include a migration guide, and provide a minimum 90-day transition period.

2. What is a sunset date and why is it important?

A sunset date is when a deprecated feature is removed. It gives developers a deadline for migration.

3. How can changelogs be automated?

Using GitHub Actions or similar tools that generate changelogs from conventional commit messages.

4. What is the recommended deprecation period for API changes?

90 days minimum for breaking changes, allowing developers time to migrate.

5. Challenge: Write release notes for a hypothetical API v2.1.0 release. Include one new feature, one improvement, one deprecation with sunset date, and one breaking change with migration guide.

FAQ

Mini Project

Create a changelog and release notes system for a sample API. Write release notes for three versions (v1.0.0, v1.1.0, v2.0.0). Include breaking changes with migration guides, deprecation notices with sunset dates, and automate the changelog format.

What's Next

After changelogs, learn about the Community Forum component of developer portals for peer support and discussions.