Release Notes and Change Communication

Effective release notes and change communication ensure users understand what's new, what's changed, and how to adapt, building trust and reducing support burden.

Overview

Release notes document changes delivered in each release, helping users understand new features, improvements, bug fixes, and breaking changes. They bridge the gap between technical changes and user impact.

Purpose

Release notes answer three questions: "What changed?" "Why should I care?" and "What do I need to do?"

Core Principles

User-Focused: Written for users, not developers - use their language and perspective
Actionable: Clearly explain what users need to do (especially for breaking changes)
Timely: Published with each release, not weeks later
Concise: Respect readers' time - summarize clearly without unnecessary detail
Accurate: Never mislead or exaggerate - trust is critical

Release Notes Structure

Recommended Format

# Release v2.5.0 - November 10, 2025

**Released**: 2025-11-10
**Type**: Minor Release
**Deployment**: Rolling deployment over 2 hours starting 10:00 AM UTC

---

## New Features

### Feature Name
Brief description of what this feature does and why it's valuable.

**Benefits**:
- Benefit 1
- Benefit 2

**How to use**:
[Basic usage instructions or link to documentation]

**Example**:
```java
// Code example if applicable

Enhancements

Enhancement Title

Description of improvement to existing functionality.

Impact: [Who benefits and how]

Bug Fixes

Bug Fix Title

Description of bug fixed and previous behavior.

Fixed: [What now works correctly] Previous Behavior: [What was broken]

Breaking Changes

Breaking Change Title

Clear description of what changed and why.

Impact: [Who is affected] Action Required: [Step-by-step migration instructions] Deadline: [When old behavior will be removed, if applicable]

Migration Example:

// Before
oldMethod();

// After
newMethod();

Deprecations

Deprecated Feature

Description of what's being deprecated and why.

Deprecated: [What is deprecated] Alternative: [What to use instead] Removal Date: [When this will be removed] Migration Guide: [Link to detailed migration guide]

Security Updates

Security Fix Title

Description of security issue fixed (without exposing vulnerability details).

Severity: [Critical / High / Medium / Low] Impact: [What was vulnerable] Action Required: [What users should do]

Performance Improvements

Performance Improvement Title

Description of performance optimization.

Improvement: [Measured improvement, e.g., "30% faster query execution"] Impact: [Who benefits]

Removals

Removed Feature

Description of feature removed.

Removed: [What was removed] Reason: [Why it was removed] Alternative: [What to use instead, if applicable]

Technical Changes

Technical Change Title

Backend or infrastructure changes that may interest technical users.

Changed: [What changed] Impact: [How this affects advanced users or integrations]

Documentation

New: Payment API Guide
Updated: Authentication Documentation
Migration Guide: v2.4.x to v2.5.0

Thank You

Thank you to all contributors who made this release possible: @contributor1, @contributor2, @contributor3

Special thanks to @contributor4 for implementing the highly-requested payment scheduling feature.

Upgrade Instructions

For Cloud Users

No action required. Your instance will be upgraded automatically during the deployment window (10:00 AM - 12:00 PM UTC).

For Self-Hosted Users

Prerequisites:

Current version must be v2.4.0 or later
Database backup recommended before upgrade
Review breaking changes section above

Upgrade Steps:

Backup your database: ./scripts/backup.sh
Download v2.5.0: wget https://releases.company.com/v2.5.0.tar.gz
Stop services: docker-compose down
Extract new version: tar -xzf v2.5.0.tar.gz
Run migrations: ./scripts/migrate.sh
Start services: docker-compose up -d
Verify health: curl http://localhost:8080/health

Rollback: If issues occur, rollback to v2.4.0:

Stop services: docker-compose down
Restore backup: ./scripts/restore.sh backup-2025-11-10.sql
Revert to v2.4.0 containers: docker-compose -f docker-compose.v2.4.0.yml up -d

Need Help?

Documentation: https://docs.company.com
Support: [email protected]
Community Forum: https://community.company.com
GitHub Issues: https://github.com/org/repo/issues

---

## Audience-Appropriate Communication

Different audiences need different levels of detail and different framing. Tailor release notes to your audience.

### Internal vs External

**Internal Release Notes** (Engineering Team):
- Include technical implementation details
- Reference Jira tickets and pull requests
- Mention internal tools and systems
- List all changes, even minor ones
- Use technical language and jargon freely

**Example**:
```markdown
## Internal Technical Changes

### Database Connection Pool Tuning (JIRA-5678)
- Increased HikariCP max pool size from 20 to 50 connections
- Added connection leak detection with 30-second threshold
- Implemented connection pool usage monitoring (Prometheus metrics)

**Pull Request**: #2345
**Deployment**: Requires restart of payment-service pods
**Monitoring**: Watch Grafana dashboard "Database Connections" for 24 hours post-deployment

External Release Notes (Customers):

Focus on user-visible changes only
Use customer terminology (not internal names)
Omit implementation details
Highlight benefits and value
Use accessible, jargon-free language

Example:

## Performance Improvements

### Faster Payment Processing
We've optimized our payment infrastructure to handle higher transaction volumes with better reliability.

**What you'll notice**:
- 40% faster payment confirmation times during peak hours
- More consistent performance under high load
- Improved reliability for large batch payments

Technical vs Non-Technical

Technical Audience (Developers integrating with API):

Include API changes with request/response examples
Document breaking changes with migration code snippets
List deprecated endpoints with alternatives
Provide OpenAPI specification links
Include versioning details

Example:

## API Changes

### Breaking: Payment Status Endpoint Response Format

**Endpoint**: `GET /api/v2/payments/{id}/status`

**What Changed**:
Response field `status` now uses standardized enum values instead of free-text.

**Before** (v2.4):
```json
{
  "status": "payment successful"
}

After (v2.5):

{
  "status": "COMPLETED",
  "statusMessage": "Payment successfully processed"
}

Migration: Update your client code to handle standardized enum values:

"payment successful" -> "COMPLETED"
"payment failed" -> "FAILED"
"processing payment" -> "PROCESSING"

See full enum documentation.

**Non-Technical Audience** (Business users, product managers):
- Focus on business value and user experience
- Use screenshots and visuals where helpful
- Avoid code examples and technical jargon
- Explain "what" and "why", not "how"
- Highlight ROI and customer impact

**Example**:
```markdown
## New: Scheduled Payment Transfers

You can now schedule future transfers up to 90 days in advance, perfect for recurring payments, payroll, or planned expenses.

**How it helps**:
- Set up recurring monthly payments once instead of manually each month
- Schedule payments ahead of time and never miss a due date
- Review and cancel scheduled transfers before they execute

**How to use**:
1. Navigate to "Transfers" -> "Schedule Transfer"
2. Enter transfer details and select future date
3. Review scheduled transfers in "Upcoming Transfers" dashboard

[Watch video tutorial](https://www.company.com/tutorials/scheduled-transfers)

Changelog vs Release Notes

Changelog and release notes serve different purposes and audiences.

Changelog

Purpose: Comprehensive, chronological record of all changes for developers and maintainers.

Audience: Developers, contributors, maintainers

Format: Typically plain text or markdown file (CHANGELOG.md) in repository

Content: Exhaustive list of every change, including:

Every bug fix (no matter how small)
Every internal refactor
Every dependency update
Links to pull requests and commits

Example (CHANGELOG.md):

# Changelog

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

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

## [2.5.0] - 2025-11-10

### Added
- Payment scheduling feature (#2345)
- Connection leak detection for database pool (#2367)
- Prometheus metrics for connection pool usage (#2367)
- Retry logic for failed notification deliveries (#2389)

### Changed
- Increased database connection pool max size from 20 to 50 (#2367)
- Updated payment status endpoint response format to use enums (#2401)
- Migrated from Spring Boot 3.4 to 3.5 (#2412)
- Upgraded Gradle from 8.4 to 8.5 (#2418)

### Fixed
- Fixed null pointer exception in payment reconciliation (#2356)
- Corrected timezone handling in scheduled payments (#2378)
- Resolved connection leak in ACH payment processing (#2367)
- Fixed flaky integration test in PaymentServiceTest (#2395)

### Deprecated
- `GET /api/v1/payments/status` endpoint (use v2) (#2401)
- `PaymentStatusEnum.UNKNOWN` (use `PENDING`) (#2401)

### Removed
- Legacy payment gateway integration (deprecated in v2.3.0) (#2423)

### Security
- Updated Jackson library to 2.15.3 to address CVE-2023-XXXXX (#2430)
- Added rate limiting to payment creation endpoint (#2438)

[2.5.0]: https://github.com/org/repo/compare/v2.4.0...v2.5.0

Characteristics:

Machine-readable format (can parse for automation)
Links to pull requests and issues
Follows standard format (Keep a Changelog)
Every change documented, no editorial curation
Lives in repository alongside code

Release Notes

Purpose: User-friendly summary of important changes for end users and stakeholders.

Audience: Customers, users, product managers, leadership

Format: Blog post, documentation site, email, in-app notification

Content: Curated, high-impact changes only:

New features users will notice
Breaking changes requiring action
Major bug fixes affecting user experience
Security updates requiring awareness
Omits internal refactors, minor fixes, dependency updates

Example (published to blog/docs site):

# What's New in v2.5.0

We're excited to announce version 2.5.0 with scheduled payments, improved performance, and important security updates.

## Scheduled Payment Transfers

Our most-requested feature is here! Schedule future transfers up to 90 days in advance.

[Screenshot of scheduled transfer UI]

Perfect for recurring payments, payroll, and planned expenses. Get started in the Transfers section.

[Learn more ->](https://docs.company.com/scheduled-transfers)

## Performance Improvements

- **40% faster payment confirmations** during peak hours
- **Improved reliability** for batch payment processing
- **Better handling** of high transaction volumes

## Action Required: API Response Format Change

If you integrate with our Payment Status API, please update your code to handle the new standardized response format.

[View migration guide ->](https://docs.company.com/migrations/payment-status-api)

## Security Updates

This release includes important security patches. We recommend upgrading as soon as possible.

---

**Need help upgrading?** Check out our [upgrade guide](https://docs.company.com/upgrade/v2.5.0) or [contact support](mailto:[email protected]).

Characteristics:

Narrative, human-friendly format
Focused on user value and impact
Curated for relevance (not exhaustive)
Published to customer-facing channels
Often includes visuals, tutorials, links

When to Use Which

Use Changelog:

Tracking all changes for developers
Complying with open-source conventions
Automating version management
Auditing historical changes

Use Release Notes:

Communicating with users and customers
Marketing new features
Explaining breaking changes
Building trust and transparency

Use Both: Most projects benefit from maintaining both:

Changelog in repository for complete technical record
Release Notes published for user communication

Automating Release Notes

Manual release note writing is time-consuming and error-prone. Automation ensures consistency and saves time.

Conventional Commits

Conventional Commits provide a standardized commit message format that enables automated changelog generation.

Format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

feat: New feature (adds to release notes "Features")
fix: Bug fix (adds to release notes "Bug Fixes")
docs: Documentation changes (may or may not be in release notes)
style: Code style changes (not in release notes)
refactor: Code refactoring (not in release notes)
perf: Performance improvement (adds to release notes "Performance")
test: Test changes (not in release notes)
chore: Build/tooling changes (not in release notes)

Breaking Changes: Add BREAKING CHANGE: in commit footer:

feat(api)!: change payment status response format

BREAKING CHANGE: Payment status endpoint now returns standardized enum instead of free text.
Clients must update to handle new format. See migration guide: https://docs.company.com/migration/payment-status

The ! after type/scope also indicates breaking change.

Examples:

# Feature
git commit -m "feat(payments): add scheduled payment transfers"

# Bug fix
git commit -m "fix(database): resolve connection leak in ACH processing"

# Performance improvement
git commit -m "perf(api): reduce payment processing latency by 40%"

# Breaking change
git commit -m "feat(api)!: standardize payment status response

BREAKING CHANGE: Response field 'status' now uses enum values.
Migration guide: https://docs.company.com/migration/status-api"

# Multiple paragraphs
git commit -m "feat(notifications): add retry logic for failed deliveries

Notification service now retries failed email deliveries up to 3 times
with exponential backoff. This improves reliability when email service
is temporarily unavailable.

Resolves: JIRA-2389"

Benefits:

Automated changelog generation
Automated semantic versioning
Consistent commit history
Easier code review (clear intent)

Changelog Generation Tools

semantic-release (Node.js): Fully automated version management and changelog generation.

npm install --save-dev semantic-release

Configuration (.releaserc.json):

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git"
  ]
}

What it does:

Analyzes commits since last release (using Conventional Commits)
Determines next version number (major/minor/patch)
Generates CHANGELOG.md
Creates GitHub release with notes
Publishes package (npm, Maven, etc.)
Commits and tags version

standard-version (Node.js): Manual-trigger version management and changelog generation.

npm install --save-dev standard-version

Usage:

# Generate changelog, bump version, create tag
npm run release

# Preview without committing
npm run release -- --dry-run

# First release
npm run release -- --first-release

gradle-git-changelog (Java/Gradle): Generates changelogs from Git history for Java projects.

plugins {
    id "se.bjurr.gitchangelog.git-changelog-gradle-plugin" version "1.77.2"
}

tasks.register('generateChangelog', se.bjurr.gitchangelog.plugin.gradle.GitChangelogTask) {
    file = new File("CHANGELOG.md")
    templateContent = """
# Changelog

{{#tags}}
## {{name}} ({{tagDate}})
{{#commits}}
- {{message}} ({{authorName}})
{{/commits}}
{{/tags}}
    """
}

GitHub Releases: GitHub can auto-generate release notes from pull requests.

Navigate to Releases -> Draft a new release
Click Auto-generate release notes
GitHub generates notes from merged PRs since last release
Edit and publish

Customization (.github/release.yml):

changelog:
  categories:
    - title:  New Features
      labels:
        - feature
        - enhancement
    - title:  Bug Fixes
      labels:
        - bug
        - fix
    - title:  Breaking Changes
      labels:
        - breaking-change
    - title:  Documentation
      labels:
        - documentation
  exclude:
    labels:
      - internal
      - chore

Automated Release Note Workflow

End-to-End Automation:

Developer commits using Conventional Commits:

git commit -m "feat(payments): add scheduled transfers"

Pull request merged to main branch with label feature

CI pipeline triggered on merge:

# .gitlab-ci.yml
release:
  stage: deploy
  only:
    - main
  script:
    - npm run semantic-release
    - ./scripts/notify-users.sh

semantic-release runs:
- Analyzes commits
- Bumps version (2.4.0 -> 2.5.0)
- Generates CHANGELOG.md
- Creates Git tag v2.5.0
- Creates GitHub/GitLab release
Release notes published:
- Automated email to users
- In-app notification
- Slack/Teams notification
- Documentation site updated

Benefits:

Zero manual effort for changelog generation
Consistent release note format
Immediate publication on release
Version numbers follow semantic versioning automatically

Writing Effective Release Notes

Automated generation creates the skeleton; good writing makes it valuable.

Writing Principles

Focus on Value, Not Implementation:

Bad (implementation-focused):

## Changes
- Refactored payment service to use async/await pattern
- Replaced callback-based code with promises
- Updated database connection pool configuration

Good (value-focused):

## Performance Improvements

### Faster Payment Processing
Payment confirmations are now 40% faster during peak hours, providing quicker feedback when you transfer money.

Users care about outcomes, not how you achieved them.

Use Active Voice and Plain Language:

Bad (passive, jargony):

The capability for users to schedule payments has been implemented utilizing an event-driven architecture with asynchronous job processing.

Good (active, clear):

You can now schedule payments up to 90 days in advance. Perfect for recurring bills or planned expenses.

Show, Don't Just Tell:

Bad (abstract):

Improved error messages for failed payments.

Good (concrete):

## Better Error Messages

When a payment fails, you'll now see clear explanations like:
- "Insufficient funds. Your account balance is $450, but this transfer requires $500."
- "Bank account not verified. Please verify your account before making transfers."

Instead of generic "Payment failed" errors.

Explain Breaking Changes Clearly:

Bad (vague):

API response format changed. Update your code.

Good (specific, actionable):

## Breaking Change: Payment Status API Response

**What changed**: The `GET /api/v2/payments/{id}/status` endpoint now returns standardized enum values instead of free text.

**Who's affected**: Developers integrating with our Payment Status API.

**What you need to do**: Update your code to handle new enum values:

**Before** (v2.4):
```json
{"status": "payment successful"}

After (v2.5):

{"status": "COMPLETED"}

Mapping:

"payment successful" -> "COMPLETED"
"payment failed" -> "FAILED"
"processing payment" -> "PROCESSING"

Deadline: Old format will be removed in v3.0.0 (March 2026).

Migration guide: Full documentation here

**Quantify Improvements**:

 **Bad** (vague):
```markdown
Improved performance for payment processing.

Good (quantified):

Payment processing is now 40% faster (P95 latency reduced from 800ms to 480ms), especially noticeable during peak hours.

Numbers make improvements tangible and credible.

Content Guidelines

Features Section:

Lead with benefit/value to user
Explain what problem it solves
Include usage example or screenshot
Link to full documentation

Bug Fixes Section:

Explain what was broken and impact
Describe what now works correctly
Only include fixes users would notice (not internal refactors)

Breaking Changes Section:

Mark clearly with warning icon ()
Explain what changed and why
Provide before/after comparison
Give step-by-step migration instructions
State deadline for action (if applicable)

Deprecations Section:

State what's deprecated
Explain why it's being deprecated
Provide alternative solution
Give timeline for removal
Link to migration guide

Security Updates Section:

Balance transparency with responsible disclosure
Don't expose vulnerability details (could be exploited)
Explain impact and action required
Include severity rating

Bad (too much detail):

Fixed SQL injection vulnerability in payment search endpoint caused by unsanitized user input in WHERE clause.
Exploit: `?search='; DROP TABLE payments; --`

Good (responsible):

## Security Update: Payment Search Endpoint

**Severity**: High
**Impact**: Resolved a security issue in the payment search feature.
**Action Required**: Update to v2.5.0 immediately. No user action needed.

If you have security questions, contact [email protected].

Communication Channels

Release notes should be published through multiple channels to reach different audiences.

Primary Channels

Documentation Site:

Canonical source of truth
Searchable and browseable
Organized by version
Permanent archive

Example: https://docs.company.com/releases/v2.5.0

GitHub/GitLab Releases:

Developers check here for technical changes
Automatic notifications for watchers
Tied to version tags
Includes artifact downloads

Email:

Reaches all users directly
Good for breaking changes or important updates
Allows segmentation (technical vs non-technical)
Track open rates to measure engagement

Template:

Subject:  What's New in v2.5.0: Scheduled Payments & Performance Improvements

Hi [Name],

We just released version 2.5.0 with exciting updates:

 New: Schedule future payments up to 90 days in advance
 Faster: 40% improvement in payment processing speed
 Action needed: API response format change (developers only)

[Read full release notes ->]

Questions? Reply to this email or visit our support center.

Thanks,
The [Company] Team

In-App Notifications:

Catches users when they're active
Contextual (show in relevant part of app)
Can include interactive tutorials
Track click-through rates

Example:

[Banner notification in app]
 New: Schedule payments in advance! [Learn more] [Dismiss]

Blog Post:

Narrative format for major releases
Include visuals, GIFs, videos
SEO benefits
Shareable content for marketing

Slack/Teams/Internal Channels:

For internal releases or B2B products
Quick updates without email overhead
Enables immediate Q&A
Thread for discussion

Segmented Communication

Different users care about different changes. Segment communication for relevance.

By User Type:

End users: New features, UI improvements, major bug fixes
Developers: API changes, breaking changes, deprecations, technical improvements
Admins: Configuration changes, security updates, infrastructure changes

By Impact:

High impact (breaking changes, security): Email + in-app + documentation
Medium impact (new features): In-app + documentation + blog
Low impact (minor fixes): Documentation + changelog only

Example Segmentation:

# For End Users (Email + In-App)
Subject: New Feature: Schedule Payments in Advance

We're excited to introduce scheduled payments! You can now...
[Focus on UI, benefits, how-to]

---

# For Developers (Email to API users + GitHub release)
Subject: v2.5.0 Released - Breaking API Change

Version 2.5.0 includes a breaking change to the Payment Status API...
[Focus on API changes, migration code, technical details]

---

# For Admins (Email to account admins)
Subject: v2.5.0 Security Update - Please Upgrade

This release includes important security updates...
[Focus on security, upgrade instructions, infrastructure]

Timing

When to Publish:

Before Deployment (Pre-announce):

For major releases with breaking changes
Give users time to prepare (1-2 weeks notice)
Beta/preview period for early adopters

With Deployment (Simultaneous):

Most common approach
Release notes published when deployment completes
Immediate user notification

After Deployment (Post-announce):

For gradual rollouts or canary deployments
Announce when 100% of users have new version
Avoid announcing before deployment completes (might fail)

Deployment Windows:

Avoid Friday deployments (weekend support issues)
Avoid holiday periods (low engagement, support unavailable)
Consider user time zones (deploy during low-traffic hours)

Migration Guides for Breaking Changes

Breaking changes require comprehensive migration guides to prevent user frustration.

Migration Guide Structure

# Migration Guide: v2.4.x to v2.5.0

This guide helps you upgrade from version 2.4.x to 2.5.0, including breaking changes and required actions.

---

## Overview

**Release Date**: 2025-11-10
**Breaking Changes**: 2 (API response format, deprecated endpoint removal)
**Estimated Migration Time**: 30 minutes
**Difficulty**: Medium

---

## Prerequisites

Before upgrading:

- [ ] You're currently running v2.4.0 or later (check: `GET /api/version`)
- [ ] You've reviewed the [full release notes](https://docs.company.com/releases/v2.5.0)
- [ ] You've backed up your integration code
- [ ] You have access to update your application

---

## Breaking Change #1: Payment Status API Response Format

### What Changed

The `GET /api/v2/payments/{id}/status` endpoint now returns standardized enum values instead of free-text strings.

### Who's Affected

Any application parsing the `status` field from the Payment Status API.

### Migration Steps

**Step 1**: Identify affected code

Search your codebase for:
```bash
grep -r "payment.*status" ./src
grep -r "/payments/.*/status" ./src

Step 2: Update response parsing

Before (v2.4):

interface PaymentStatusResponse {
  status: string;  // Free text like "payment successful"
}

function handleResponse(response: PaymentStatusResponse) {
  if (response.status === "payment successful") {
    // Handle success
  }
}

After (v2.5):

enum PaymentStatus {
  PENDING = "PENDING",
  PROCESSING = "PROCESSING",
  COMPLETED = "COMPLETED",
  FAILED = "FAILED",
  CANCELLED = "CANCELLED"
}

interface PaymentStatusResponse {
  status: PaymentStatus;
  statusMessage: string;  // Human-readable description
}

function handleResponse(response: PaymentStatusResponse) {
  if (response.status === PaymentStatus.COMPLETED) {
    // Handle success
  }
}

Step 3: Update status checks

Map old free-text values to new enums:

Old Value (v2.4)	New Value (v2.5)
`"payment successful"`	`PaymentStatus.COMPLETED`
`"payment failed"`	`PaymentStatus.FAILED`
`"processing payment"`	`PaymentStatus.PROCESSING`
`"payment pending"`	`PaymentStatus.PENDING`
`"payment cancelled"`	`PaymentStatus.CANCELLED`

Step 4: Test changes

// Test with mock response
const mockResponse: PaymentStatusResponse = {
  status: PaymentStatus.COMPLETED,
  statusMessage: "Payment successfully processed"
};

handleResponse(mockResponse);  // Should work

Step 5: Deploy and verify

Deploy updated code to staging
Test against staging API
Verify all status checks work correctly
Deploy to production

Timeline

Now - Dec 31, 2025: Both old and new formats supported (grace period)
Jan 1, 2026: Old format removed, new format required

Need Help?

Breaking Change #2: Legacy Gateway Removal

What Changed

Support for the legacy payment gateway (deprecated in v2.3.0) has been removed.

Who's Affected

Applications still using the POST /api/v1/payments/legacy endpoint.

Migration Steps

[Detailed steps...]

Non-Breaking Changes

These changes are backward-compatible but recommended:

Recommended: Upgrade to v2 Endpoints

While v1 endpoints still work, we recommend migrating to v2 for better performance and features:

GET /api/v1/payments -> GET /api/v2/payments (supports filtering, pagination)
POST /api/v1/transfers -> POST /api/v2/transfers (includes scheduled transfers)

[Migration details...]

Deprecation Notices

These features are deprecated and will be removed in v3.0.0 (planned March 2026):

Deprecated: Payment Batching v1 API

Deprecated: POST /api/v1/payments/batch Alternative: POST /api/v2/payments/batch Removal Date: v3.0.0 (March 2026)

Start migrating now to avoid disruption. Migration guide.

Testing Your Migration

Test Checklist

All API calls return expected responses
Error handling works for new error formats
Payment status checks work correctly
Integration tests pass
Performance is acceptable
Logs show no errors or warnings

Sample Test Cases

describe('Payment Status API Migration', () => {
  it('should handle COMPLETED status', () => {
    const response = { status: PaymentStatus.COMPLETED };
    expect(isSuccessful(response)).toBe(true);
  });

  it('should handle FAILED status', () => {
    const response = { status: PaymentStatus.FAILED };
    expect(isSuccessful(response)).toBe(false);
  });
});

Rollback Plan

If you encounter issues after upgrading:

Option 1: Stay on v2.4.x until resolved

v2.4.x remains supported until Jan 1, 2026
Fix issues at your own pace

Option 2: Rollback deployment

Restore previous version from backup
Test functionality
Report issues to support

FAQ

Q: Do I need to migrate if I only use the UI, not the API? A: No, UI-only users are upgraded automatically with no action required.

Q: Can I test the migration before deploying to production? A: Yes, use our staging environment: https://staging.api.company.com

Q: What if I miss the Jan 1, 2026 deadline? A: Your integration will break. Old format will no longer be supported. Migrate before deadline.

Q: Is there a way to automate the migration? A: We provide a migration CLI tool: Download here

Support

Need help with your migration?

Documentation: https://docs.company.com/migration/v2.5.0
Video Tutorial: https://www.company.com/videos/migration-guide
Community Forum: https://community.company.com
Email Support: [email protected]
Slack Channel: #api-migrations

We're here to help make your migration smooth!

### Migration Guide Best Practices

**Provide Code Examples**:
Show before/after code for every breaking change. Real code is more helpful than descriptions.

**Step-by-Step Instructions**:
Numbered steps reduce cognitive load. Users can follow checklist-style.

**Timeline and Deadlines**:
Clearly state grace periods and hard deadlines. Give ample warning.

**Test Cases**:
Provide sample tests users can run to verify migration success.

**Rollback Plan**:
Always provide escape hatch if migration fails.

**Support Resources**:
Link to all available help: docs, videos, community, support email.

---

## Versioning Strategy

Consistent versioning helps users understand the scope and impact of changes.

### Semantic Versioning

**Format**: `MAJOR.MINOR.PATCH` (e.g., `2.5.3`)

- **MAJOR**: Breaking changes (increment: 1.x.x -> 2.0.0)
- **MINOR**: New features, backward-compatible (increment: 2.4.x -> 2.5.0)
- **PATCH**: Bug fixes, backward-compatible (increment: 2.5.2 -> 2.5.3)

**When to Increment**:

**MAJOR** (breaking changes):
- API endpoint removed
- Response format changed incompatibly
- Required parameter added
- Behavior changed in backward-incompatible way

**MINOR** (new features):
- New API endpoint added
- New optional parameter added
- New response field added
- Existing functionality enhanced (backward-compatible)

**PATCH** (bug fixes):
- Bug fixed with no API changes
- Security patch
- Performance improvement
- Documentation correction

**Example Progression**:

v2.4.0 -> v2.4.1 (bug fix: PATCH) v2.4.1 -> v2.5.0 (new feature: MINOR) v2.5.0 -> v3.0.0 (breaking change: MAJOR)

**Pre-Release Versions**:
- **Alpha**: `2.5.0-alpha.1` (early testing, unstable)
- **Beta**: `2.5.0-beta.2` (feature-complete, testing)
- **Release Candidate**: `2.5.0-rc.1` (final testing before release)

### Calendar Versioning

Alternative to semantic versioning, especially for rapidly-released products.

**Format**: `YYYY.MM.DD` or `YY.MM.MICRO`

**Example**: `2025.11.10` (released November 10, 2025)

**When to Use**:
- Continuous delivery with frequent releases
- Changes don't fit semantic versioning well
- Users care more about recency than breaking changes
- SaaS products with automatic upgrades

**Examples**: Ubuntu (`22.04`), CalVer-using projects

---

## Further Reading

- [Technical Writing Guide](./technical-writing.md) - Writing effective documentation
- [Code Review Best Practices](./code-review.md) - Reviewing changes before release
- [Pull Request Best Practices](./pull-requests.md) - Documenting changes in PRs
- [Git Workflow](./git/git-workflow.md) - Branching and release process
- [Incident Post-Mortems](./incident-post-mortems.md) - Communicating incident resolutions

**External Resources**:
- [Keep a Changelog](https://keepachangelog.com/) - Changelog formatting standard
- [Semantic Versioning](https://semver.org/) - Versioning specification
- [Conventional Commits](https://www.conventionalcommits.org/) - Commit message standard
- [semantic-release](https://github.com/semantic-release/semantic-release) - Automated release tool
- [GitHub Release Notes Examples](https://github.com/github/releases) - Well-crafted release notes

---

## Summary

**Key Takeaways**:

1. **User-Focused**: Write for users, not developers - explain value and impact, not implementation.
2. **Audience-Appropriate**: Tailor content and channels to audience (technical vs non-technical, internal vs external).
3. **Comprehensive Breaking Changes**: Provide detailed migration guides with before/after code, steps, and deadlines.
4. **Automate Where Possible**: Use Conventional Commits and tools like semantic-release to automate changelog generation.
5. **Multiple Channels**: Publish through docs, email, in-app, blog, GitHub releases to reach all users.
6. **Timely Publication**: Release notes published with deployment (or pre-announced for breaking changes).
7. **Versioning Strategy**: Follow semantic versioning (or calendar versioning) consistently.
8. **Migration Support**: Provide guides, code examples, test cases, and support resources.
9. **Changelog vs Release Notes**: Maintain both - comprehensive changelog for developers, curated release notes for users.
10. **Action-Oriented**: Every breaking change or deprecation includes clear "what you need to do" instructions.

:::tip[Building Trust]
Transparent, timely, helpful release notes build user trust. When users know what changed, why it changed, and how to adapt, they feel informed and empowered rather than surprised and frustrated.

Invest in great release notes - they reduce support burden, increase upgrade rates, and strengthen customer relationships.
:::

Overview​

Core Principles​

Release Notes Structure​

Recommended Format​

Enhancements​

Enhancement Title​

Bug Fixes​

Bug Fix Title​

Breaking Changes​

Breaking Change Title​

Deprecations​

Deprecated Feature​

Security Updates​

Security Fix Title​

Performance Improvements​

Performance Improvement Title​

Removals​

Removed Feature​

Technical Changes​

Technical Change Title​

Documentation​

Links​

Thank You​

Upgrade Instructions​

For Cloud Users​

For Self-Hosted Users​

Need Help?​

Technical vs Non-Technical​

Changelog vs Release Notes​

Changelog​

Release Notes​

When to Use Which​

Automating Release Notes​

Conventional Commits​

Changelog Generation Tools​

Automated Release Note Workflow​

Writing Effective Release Notes​

Writing Principles​

Content Guidelines​

Communication Channels​

Primary Channels​

Segmented Communication​

Timing​

Migration Guides for Breaking Changes​

Migration Guide Structure​

Timeline​

Need Help?​

Breaking Change #2: Legacy Gateway Removal​

What Changed​

Who's Affected​

Migration Steps​

Non-Breaking Changes​

Recommended: Upgrade to v2 Endpoints​

Deprecation Notices​

Deprecated: Payment Batching v1 API​

Testing Your Migration​

Test Checklist​

Sample Test Cases​

Rollback Plan​

FAQ​

Support​

Overview

Core Principles

Release Notes Structure

Recommended Format

Enhancements

Enhancement Title

Bug Fixes

Bug Fix Title

Breaking Changes

Breaking Change Title

Deprecations

Deprecated Feature

Security Updates

Security Fix Title

Performance Improvements

Performance Improvement Title

Removals

Removed Feature

Technical Changes

Technical Change Title

Documentation

Links

Thank You

Upgrade Instructions

For Cloud Users

For Self-Hosted Users

Need Help?

Technical vs Non-Technical

Changelog vs Release Notes

Changelog

Release Notes

When to Use Which

Automating Release Notes

Conventional Commits

Changelog Generation Tools

Automated Release Note Workflow

Writing Effective Release Notes

Writing Principles

Content Guidelines

Communication Channels

Primary Channels

Segmented Communication

Timing

Migration Guides for Breaking Changes

Migration Guide Structure

Timeline

Need Help?

Breaking Change #2: Legacy Gateway Removal

What Changed

Who's Affected

Migration Steps

Non-Breaking Changes

Recommended: Upgrade to v2 Endpoints

Deprecation Notices

Deprecated: Payment Batching v1 API

Testing Your Migration

Test Checklist

Sample Test Cases

Rollback Plan

FAQ

Support