Changelog Guide

Format: Keep a Changelog

Follow the Keep a Changelog convention. Every release gets a section with the version number, date, and categorized entries.

# 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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features not yet released

## [2.3.0] - 2026-03-14

### Added
- `client.users.archive()` method for soft-deleting users (#342)
- TypeScript 5.4 support with improved type inference (#355)

### Changed
- `client.users.list()` now returns paginated results by default.
  Pass `{ paginate: false }` to restore previous behavior. (#338)

### Deprecated
- `client.users.delete()` is deprecated in favor of `client.users.archive()`.
  Will be removed in v3.0. See [migration guide](/docs/migrate-v2.3). (#342)

### Fixed
- `client.invoices.send()` no longer throws on zero-amount invoices (#401)
- Rate limit headers now correctly parsed on HTTP/2 connections (#398)

### Security
- Updated `xml-parser` dependency to fix CVE-2026-1234 (#410)

## [2.2.1] - 2026-02-28
...

Change categories

Use exactly these categories, in this order. Omit empty categories.

Writing good changelog entries

The three-question test

Every entry must answer:

1. What changed? (the fact)
2. Why does the developer care? (the impact)
3. What should they do? (the action, if any)

Good vs bad entries

Bad:

- Updated user module
- Various bug fixes
- Improved performance

Good:

- `client.users.list()` now returns results sorted by `created_at` descending
  by default. Pass `{ sort: "created_at:asc" }` to restore previous behavior. (#338)
- Fixed: `client.webhooks.verify()` returned false for payloads containing
  unicode characters (#401)
- `client.search()` is now 3x faster for queries with > 1000 results due to
  cursor-based pagination replacing offset pagination (#412)

Entry format rules

• Start with the affected method, class, or feature in backticks
• Use present tense ("adds", "fixes", "removes") or past tense consistently - pick one
• Link to the issue or PR with a parenthetical reference (#123)
• For Changed and Removed: always include the migration action
• For Deprecated: always state when it will be removed (version or date)
• For Security: reference the CVE number

Semantic versioning rules

What counts as a breaking change

• Removing or renaming a public method, class, or parameter
• Changing the return type of a public method
• Changing the default value of a parameter in a way that alters behavior
• Dropping support for a runtime version (Node 14, Python 3.8, etc.)
• Changing error types that consumers might be catching

What does NOT count as breaking

• Adding a new optional parameter
• Adding a new method to an existing resource
• Fixing a bug (unless consumers depend on the buggy behavior - document this)
• Internal refactoring that doesn't change the public API

Deprecation communication playbook

Step 1: Announce deprecation (minor release)

### Deprecated
- `client.users.delete()` is deprecated. Use `client.users.archive()` instead.
  `delete()` will be removed in v3.0 (estimated Q3 2026).
  See [migration guide](/docs/migrate-delete-to-archive).

Step 2: Runtime deprecation warning

Add a runtime warning that fires when the deprecated method is called:

/** @deprecated Use archive() instead. Will be removed in v3.0. */
async delete(id: string): Promise<void> {
  console.warn(
    "[acme-sdk] users.delete() is deprecated. Use users.archive() instead. " +
    "See: https://docs.acme.com/migrate-delete-to-archive"
  );
  return this.archive(id);
}

Step 3: Remove in major release

### Removed
- `client.users.delete()` has been removed. Use `client.users.archive()`.
  See [v3 migration guide](/docs/migrate-v3).

Deprecation timeline rules

• Minimum 1 minor release between deprecation announcement and removal
• Minimum 3 months calendar time for widely-used features
• Always provide the replacement in the deprecation notice
• Never deprecate without a migration path

Automating changelogs

From conventional commits

If using conventional commit messages (feat:, fix:, breaking:), generate changelog entries automatically:

# Generate changelog from git history
npx conventional-changelog -p angular -i CHANGELOG.md -s

From PR labels

Use GitHub labels (breaking, feature, fix, deprecation) and generate changelog entries from merged PRs between releases.

Human review is still required

Automated changelogs capture the "what" but miss the "why" and "what to do." Always have a human review and enhance automated entries before publishing.

Release notes vs changelog

Write the changelog first, then derive release notes from it. Never the reverse.

Migration Guide Template and Patterns

Migration guide template

Use this structure for every major version migration guide.

# Migrating from v<X> to v<Y>

## Who needs to migrate

<Describe which users are affected. Be specific - "all users" is rarely true.>

- Users of `client.payments.create()` (method signature changed)
- Users with custom retry logic (retry config format changed)
- Node.js 16 users (minimum version is now Node.js 18)

## Timeline

- **v<Y> release date:** YYYY-MM-DD
- **v<X> end of support:** YYYY-MM-DD (security patches only until then)
- **v<X> end of life:** YYYY-MM-DD (no further updates)

## Quick upgrade

For most users, the upgrade is:

  npm install @acme/sdk@<Y>
  npx @acme/migrate v<X>-to-v<Y>  # automated codemod (if available)

## Breaking changes

### 1. <Change title>

**What changed:** <factual description>
**Why:** <motivation - helps developers accept the change>

**Before (v<X>):**
  <old code>

**After (v<Y>):**
  <new code>

**Automated fix:** `npx @acme/migrate <specific-codemod>`
  or
**Manual fix:** <step-by-step instructions>

### 2. <Next change>
...

## Non-breaking changes worth knowing

<Optional: notable improvements that don't require action but developers
should be aware of>

## Verification

After migrating, verify your integration:

  npm test                              # run your test suite
  npx @acme/sdk doctor                  # built-in health check (if available)
  curl https://api.acme.com/v2/health   # verify API connectivity

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `TypeError: client.payments.create is not a function` | Using old method name | Rename to `client.paymentIntents.create()` |
| `AcmeVersionError: Unsupported API version` | SDK and API version mismatch | Set `apiVersion: "2026-01-15"` in constructor |
| ... | ... | ... |

## Getting help

- [GitHub Discussions](link) - ask the community
- [Discord #migration channel](link) - real-time help
- [Support ticket](link) - for blocking issues

Breaking change classification

Not all breaking changes are equal. Classify them to set developer expectations:

High-severity changes need the most communication because developers may not notice the change until it causes production issues.

Codemod patterns

Codemods are automated code transformations that handle mechanical migration tasks. They dramatically reduce migration cost.

When to provide a codemod

• Method or parameter renames (mechanical find-and-replace)
• Import path changes
• Configuration format changes
• Any change affecting > 100 call sites in a typical codebase

When NOT to provide a codemod

• Logic changes that require human judgment
• Changes where the old and new patterns aren't 1:1 mappings
• Changes that affect < 5 call sites in a typical codebase

Codemod implementation options

JavaScript/TypeScript - jscodeshift:

// transforms/rename-create-payment.js
module.exports = function(fileInfo, api) {
  const j = api.jscodeshift;
  return j(fileInfo.source)
    .find(j.MemberExpression, {
      property: { name: "createPayment" }
    })
    .forEach(path => {
      path.node.property.name = "createPaymentIntent";
    })
    .toSource();
};

Python - libcst:

import libcst as cst

class RenameCreatePayment(cst.CSTTransformer):
    def leave_Call(self, original_node, updated_node):
        if m.matches(updated_node.func, m.Attribute(attr=m.Name("create_payment"))):
            return updated_node.with_changes(
                func=updated_node.func.with_changes(
                    attr=cst.Name("create_payment_intent")
                )
            )
        return updated_node

CLI wrapper:

# Package the codemod as a CLI tool
npx @acme/migrate rename-create-payment --dir ./src
# Output: Transformed 23 files, 47 call sites updated

Codemod testing

• Test against a fixture directory with known input/output pairs
• Include edge cases: dynamic property access, aliased imports, string references
• Run the codemod on your own SDK's test suite as a smoke test

Multi-version support strategy

When maintaining multiple major versions simultaneously:

Support matrix

Branch strategy

main           -> v3.x (current)
release/v2     -> v2.x (maintenance - cherry-pick critical fixes)
release/v1     -> v1.x (archived, no changes)

Documentation strategy

• Default docs show the current version
• Provide a version switcher for at least current and previous major
• Archive older versions at a stable URL (e.g., /docs/v1/)
• Never delete old docs - developers on legacy versions need them

Communication channels for breaking changes

Use multiple channels based on change severity:

Communication timeline

1. T-6 months: Announce upcoming major version in blog + email
2. T-3 months: Release beta/RC with migration guide
3. T-0: Release major version, begin previous version maintenance period
4. T+6 months: Send reminder emails about previous version EOL
5. T+12 months: End of life for previous version

Migration checklist for SDK authors

Before releasing a major version:

• Every breaking change has a before/after code example
• Migration guide is written and reviewed by someone who didn't make the changes
• Codemods exist for all mechanical changes
• Codemods are tested against real-world codebases (not just unit tests)
• Previous version has a documented end-of-support date
• Previous version docs are archived at a stable URL
• Deprecation warnings were shipped at least one minor version ago
• Changelog is complete with all breaking changes categorized
• Blog post / email / announcement is drafted
• Support team is briefed on common migration questions

Developer Onboarding Framework

The five-minute rule

A developer should go from "I have never used this tool" to "I got a working result" in under five minutes. This is the single most important DX metric.

To achieve this:

• Installation must be a single command
• Authentication must be copy-paste (test key, sandbox, or local mode)
• The first example must produce a visible, meaningful result
• No account creation should be required for the first experience

Quickstart template

Every quickstart follows this structure. Do not deviate.

# Quickstart

<Tool Name> lets you <one-sentence value prop>.

## Prerequisites

- <Language> >= <version>
- A <Tool Name> account ([sign up free](link)) -- only if truly required

## Install

  <single install command>

## Set your API key

  export TOOL_API_KEY=your-test-key-here

Get a test key at: <link to dashboard>

## Send your first <thing>

  <5-15 lines of code that produce a visible result>

Run it:

  <command to execute>

You should see:

  <expected output>

## Next steps

- [Send a <thing> with custom options](/docs/guides/custom-options)
- [Handle errors and retries](/docs/guides/error-handling)
- [Go to production](/docs/guides/production-checklist)

Quickstart anti-patterns

Tutorial structure

Tutorials go deeper than quickstarts. They teach one complete workflow.

Template

# <Verb> + <Noun> (e.g. "Send a transactional email")

In this tutorial you will:
1. <Step 1 outcome>
2. <Step 2 outcome>
3. <Step 3 outcome>

**Time:** ~10 minutes
**Prerequisites:** Completed the [Quickstart](/docs/quickstart)

## Step 1: <Action>

<1-2 sentences of context>

  <code block>

<Explain what happened and why>

## Step 2: <Action>
...

## What you built

<Summary of what the developer accomplished>

## Next steps

- <Related tutorial 1>
- <Related tutorial 2>

Tutorial principles

• One tutorial = one workflow (don't combine "send email" and "set up webhooks")
• Every step must produce a verifiable intermediate result
• Show the code first, explain after
• Time estimates must be honest - test them with a fresh developer

Developer portal structure

Information architecture

Organize docs by developer intent, not by product structure:

/docs
  /quickstart          - First 5 minutes
  /guides              - Task-oriented walkthroughs
    /authentication
    /sending-emails
    /handling-webhooks
    /going-to-production
  /api-reference       - Every method, parameter, type
  /changelog           - What changed and when
  /migration           - Upgrade guides for breaking changes
  /sdks                - Language-specific setup and quirks
  /examples            - Copy-paste recipes for common patterns

Navigation principles

• Use task-oriented labels ("Send an email") not feature-oriented ("Email API")
• Put quickstart in the top-level navigation, never buried in a submenu
• Provide a search that covers docs, API reference, and changelog
• Show the most recent SDK version prominently with a version switcher

Onboarding email sequence

For tools with accounts, design the onboarding email sequence around DX milestones:

Segmentation

• Detect the developer's language/framework from their first API call
• Tailor follow-up emails with language-specific examples
• Track activation metrics: installed SDK, made first API call, integrated in app

Measuring onboarding success

Common onboarding pitfalls

1. Requiring production credentials for sandbox - Always offer test/sandbox keys that work immediately without approval workflows
2. Docs lag behind SDK releases - Automate doc generation from code; never let docs be more than one release behind
3. No copy button on code blocks - Small friction multiplied by every developer on every page
4. Assuming framework knowledge - Not every Node.js developer uses Express; show framework-agnostic examples first
5. Hiding the pricing page - Developers evaluate cost early; making them hunt for pricing destroys trust

SDK Design Checklist

Naming conventions

Methods

• Use verb-noun pairs: createUser, listInvoices, deleteWebhook
• Use consistent verbs across resources: create, get, list, update, delete
• Avoid ambiguous verbs: handle, process, manage, do
• Boolean methods start with is, has, can, should
• Avoid negated names: isEnabled not isNotDisabled

Resources

• Use the same noun the API uses (don't rename payment_intent to charge)
• Plural for collections: client.users.list() not client.user.list()
• Singular for singletons: client.account.get() not client.accounts.get()

Parameters

• Required params go in the function signature positionally
• Optional params go in a trailing options/config object
• Never use positional booleans: send(email, true) - what does true mean?

// Bad: positional boolean
await client.emails.send("user@example.com", true, false);

// Good: options object
await client.emails.send("user@example.com", {
  trackOpens: true,
  trackClicks: false,
});

Constructor and configuration

Minimum viable constructor

The constructor should require only what is truly necessary to authenticate. Everything else gets a sensible default.

// Minimum: just the API key
const client = new Acme({ apiKey: "sk_..." });

// Optional overrides for advanced use cases
const client = new Acme({
  apiKey: "sk_...",
  baseUrl: "https://api.staging.acme.com",
  timeout: 30_000,
  retries: 3,
  logger: customLogger,
});

Environment variable fallback

SDKs should check for well-known environment variables when no explicit config is provided. Document which env vars are checked.

// Constructor checks process.env.ACME_API_KEY if apiKey is omitted
const client = new Acme(); // works if ACME_API_KEY is set

Return types and error handling

Consistent return shapes

Every method should return the same shape for success. Use typed errors for failure - never return null to indicate an error.

// Good: consistent returns
const user = await client.users.get("usr_123"); // returns User
const users = await client.users.list();          // returns User[]

// Good: typed errors
try {
  await client.users.get("usr_999");
} catch (error) {
  if (error instanceof AcmeNotFoundError) {
    // handle 404
  }
}

Error hierarchy

Design a small, useful error hierarchy:

AcmeError (base)
  AcmeApiError (any API response error)
    AcmeNotFoundError (404)
    AcmeValidationError (400/422)
    AcmeAuthError (401/403)
    AcmeRateLimitError (429)
  AcmeConnectionError (network failures)
  AcmeTimeoutError (request timeout)

Every error should include:

• Human-readable message with fix suggestion
• HTTP status code (if from API)
• Request ID for support escalation
• Original response body for debugging

Pagination

Never return unbounded lists. Default to paginated responses.

// Cursor-based pagination (preferred)
const page1 = await client.users.list({ limit: 20 });
const page2 = await client.users.list({ limit: 20, after: page1.cursor });

// Convenience: auto-pagination iterator
for await (const user of client.users.list({ limit: 20 })) {
  console.log(user.email);
}

Idempotency

For any operation that creates or mutates state, support idempotency keys:

await client.payments.create(
  { amount: 1000, currency: "usd" },
  { idempotencyKey: "order_abc_payment_1" }
);

Document clearly which methods are idempotent by default and which require an explicit key.

Extensibility

Middleware / hooks

Allow consumers to intercept requests for logging, metrics, or custom headers:

const client = new Acme({
  apiKey: "sk_...",
  beforeRequest: (req) => {
    req.headers["X-Request-Source"] = "my-service";
    return req;
  },
  afterResponse: (res) => {
    metrics.record("acme_api_call", { status: res.status });
    return res;
  },
});

Custom HTTP client

Allow injecting a custom HTTP client for environments with specific networking requirements (proxies, custom TLS, etc.).

Versioning

• Follow semantic versioning strictly
• Never ship breaking changes in minor or patch releases
• Use header-based API versioning (Acme-Version: 2024-01-15) over URL versioning
• Document the SDK-to-API version mapping clearly
• Support at least the current and previous major API version simultaneously

Testing support

Make the SDK testable without hitting the real API:

// Provide a mock/test mode
const client = new Acme({ apiKey: "sk_test_..." }); // test mode by key prefix

// Or provide explicit test helpers
import { createMockClient } from "@acme/sdk/testing";
const mock = createMockClient();
mock.users.get.mockResolvedValue({ id: "usr_123", email: "test@example.com" });

Documentation requirements for SDKs

Every SDK must ship with:

1. README with install + quickstart (< 30 lines of code to first result)
2. API reference generated from types/docstrings (not hand-written)
3. At least 3 guides covering the most common workflows
4. Changelog following Keep a Changelog format
5. Migration guide for every major version bump