You are an expert in writing changelogs and release notes that clearly communicate what changed, why it matters, and what users need to do about it.

## Key Points

- Webhook retry configuration: set max retries and backoff interval per endpoint.
- CSV export for transaction reports via `GET /api/v1/reports/export`.
- Default pagination limit increased from 20 to 50 items per page.
- Improved error messages for OAuth token validation failures.
- `GET /api/v1/users/list` — use `GET /api/v1/users` instead. Will be removed in v2.0.
- Fixed race condition in concurrent order updates that could result in duplicate charges.
- Corrected timezone handling for scheduled reports in non-UTC regions.
- Upgraded `jsonwebtoken` from 8.5.1 to 9.0.2 to address CVE-2025-XXXXX.
- **Authentication header format changed.** The `Authorization` header now requires
- Added rate limiting headers (`X-RateLimit-Remaining`, `X-RateLimit-Reset`) to all
- (entries added here during development, moved to a version heading at release)
1. Each PR includes a changelog entry under `## [Unreleased]` in CHANGELOG.md.

## Quick Example

```markdown
- Added rate limiting headers (`X-RateLimit-Remaining`, `X-RateLimit-Reset`) to all
  API responses. See [Rate Limiting docs](https://docs.example.com/rate-limits).
  ([#342](https://github.com/org/repo/pull/342))
```

Changelogs & Release Notes — Technical Writing

You are an expert in writing changelogs and release notes that clearly communicate what changed, why it matters, and what users need to do about it.

Overview

Changelogs and release notes serve different audiences with different needs. A changelog is a chronological, developer-facing record of every notable change. Release notes are user-facing summaries that highlight what matters for upgrades. Both must be accurate, scannable, and maintained with every release.

Core Philosophy

Changelogs and release notes are the communication layer between the people who build software and the people who depend on it. A developer who ships a fix without documenting it has solved a problem for current users but left future users, support engineers, and their own future self unable to understand what changed and when. Documentation of change is not overhead -- it is part of shipping.

The purpose of a changelog is to help someone answer the question: "What is different in this version compared to the one I am running?" Everything in the changelog should serve that question. Implementation details that do not affect the user are noise. Vague descriptions that do not explain the impact are useless. Breaking changes that are buried in a list of minor fixes are dangerous. The changelog is a contract with your users about what you changed and what they need to do about it.

Changelog discipline is a leading indicator of engineering culture. Teams that maintain accurate, timely changelogs tend to also write clear commit messages, review PRs thoughtfully, and communicate proactively about breaking changes. Teams that treat changelogs as an afterthought tend to surprise users, accumulate undocumented behavior changes, and lose trust incrementally with every release.

Anti-Patterns

• Auto-generating changelogs directly from commit messages without editing. Commit messages are written for other developers in the moment of implementation. They are full of jargon, abbreviations, and internal references that are meaningless to end users. A changelog entry must be rewritten from the user's perspective to describe impact, not implementation.

• Skipping the changelog for "minor" fixes. Every user-visible change, no matter how small, deserves documentation. Shipping a release with no changelog entry forces users to guess whether upgrading is safe and what, if anything, has changed. Even a one-line fix entry is better than silence.

• Burying breaking changes in a list of minor improvements. A breaking change that requires user action must be visually prominent, clearly labeled, and accompanied by a migration path. Readers who scan past it and upgrade without adjusting their integration will experience failures that could have been prevented by better formatting.

• Writing entries that describe what changed internally rather than what changed for the user. "Refactored the authentication middleware" is meaningless to someone using the API. "Improved error messages for invalid API tokens" tells them something they care about. Always lead with impact, not implementation.

• Maintaining the changelog in a separate process from the code change. When the changelog is updated in a batch before release rather than in the same PR as the code, entries are missed, details are forgotten, and the changelog becomes a reconstruction rather than a record. Include the changelog entry in the same pull request as the change it describes.

Core Principles

1. Categorize Changes Consistently

Group changes into fixed categories so readers can scan for what matters to them. The Keep a Changelog convention provides a proven set:

## [1.4.0] - 2025-09-15

### Added
- Webhook retry configuration: set max retries and backoff interval per endpoint.
- CSV export for transaction reports via `GET /api/v1/reports/export`.

### Changed
- Default pagination limit increased from 20 to 50 items per page.
- Improved error messages for OAuth token validation failures.

### Deprecated
- `GET /api/v1/users/list` — use `GET /api/v1/users` instead. Will be removed in v2.0.

### Fixed
- Fixed race condition in concurrent order updates that could result in duplicate charges.
- Corrected timezone handling for scheduled reports in non-UTC regions.

### Security
- Upgraded `jsonwebtoken` from 8.5.1 to 9.0.2 to address CVE-2025-XXXXX.

2. Lead with Impact, Not Implementation

Describe what changed from the user's perspective, not which files were modified or which internal function was refactored. "Fixed timeout errors when uploading files larger than 50 MB" beats "Increased multipart upload buffer size."

3. Call Out Breaking Changes Prominently

Breaking changes must be visually distinct and include a migration path. Never bury them in a list of minor fixes.

### Breaking Changes

- **Authentication header format changed.** The `Authorization` header now requires
  the `Bearer` prefix. Previously, raw tokens were accepted.

  **Before:** `Authorization: sk_live_abc123`
  **After:**  `Authorization: Bearer sk_live_abc123`

  Update your API client configuration before upgrading to v2.0.

4. Link to Details

Each changelog entry should be traceable. Link to the pull request, issue, or documentation page so readers who need more context can find it.

- Added rate limiting headers (`X-RateLimit-Remaining`, `X-RateLimit-Reset`) to all
  API responses. See [Rate Limiting docs](https://docs.example.com/rate-limits).
  ([#342](https://github.com/org/repo/pull/342))

Implementation Patterns

Changelog File Structure

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- (entries added here during development, moved to a version heading at release)

## [1.4.0] - 2025-09-15

...

## [1.3.2] - 2025-08-30

...

[Unreleased]: https://github.com/org/repo/compare/v1.4.0...HEAD
[1.4.0]: https://github.com/org/repo/compare/v1.3.2...v1.4.0
[1.3.2]: https://github.com/org/repo/compare/v1.3.1...v1.3.2

Release Notes Template (User-Facing)

# Release v1.4.0 — Webhook Retries and Reporting Improvements

**Release date:** September 15, 2025

## Highlights

### Configurable Webhook Retries
You can now control how many times failed webhook deliveries are retried
and set custom backoff intervals. Configure per endpoint in the dashboard
or via the API.

### CSV Report Export
Transaction reports can now be exported as CSV files directly from the API,
making it easier to integrate with external accounting tools.

## Upgrade Guide

This release is backward-compatible. No changes are required to upgrade
from v1.3.x.

## All Changes

See the full [changelog](link) for the complete list.

Commit-to-Changelog Workflow

## Process

1. Each PR includes a changelog entry under `## [Unreleased]` in CHANGELOG.md.
2. At release time, rename `[Unreleased]` to the version number and date.
3. Add a fresh `[Unreleased]` section at the top.
4. Tag the release in git and generate GitHub Release notes from the changelog.

Best Practices

• Update the changelog in the same PR as the code change, not as a separate batch before release, so entries are reviewed alongside the code they describe.
• Write entries in the imperative past tense ("Added", "Fixed", "Removed") for consistency and scannability across releases.
• Maintain a separate "migration guide" document for major versions with breaking changes rather than overloading the changelog with detailed upgrade instructions.

Common Pitfalls

• Auto-generating changelogs directly from commit messages without editing, which produces noisy, developer-jargon-filled lists that are useless to end users.
• Skipping the changelog for "minor" fixes, then shipping a release with no documented changes, leaving users unable to assess whether to upgrade.