Release Notes Template for Developer Tools
Developer tool release notes serve a fundamentally different purpose than consumer app release notes. Developers reading your release notes are evaluating one question first: "Will this update break my integration?" Everything else comes second. The structure must answer that question in the first five seconds — which means breaking changes must be listed first, in full, with exact code changes required, not buried after a list of new features.
This template is designed for teams shipping APIs, SDKs, CLI tools, developer platforms, and any product where the primary user is a developer who has written code against your interface. It covers the full changelog structure — from breaking changes with migration guides through new capabilities, deprecation notices, and bug fixes — in the order and format that developer audiences expect.
What developers actually need in release notes
Developer trust is built by predictability. Teams that publish well-structured, complete release notes for every version create integrations that stay updated. Teams that publish incomplete or inconsistent notes — or skip releases entirely — create integrations that are pinned to old versions and accumulate technical debt. The quality of your release notes directly affects how current your users' integrations are.
Breaking changes are the highest-stakes communication in any developer tool's release cycle. A breaking change that is not clearly documented and communicated causes production incidents for your customers. A breaking change that is documented with a complete migration guide, appropriate notice period, and a clear removal date is manageable. The difference between these outcomes is entirely in how you communicate the change, not in whether you make the change.
Deprecation notices deserve special attention. The best practice is to announce deprecations well in advance (typically 6–12 months), include the deprecated behavior in every release note until removal, add runtime warnings in the SDK, and provide concrete code examples of the migration. Teams that do all four of these things experience much smoother migrations than teams that announce deprecation once and assume developers read every release note.
Template sections
5 sections covering the complete release notes workflow.
Breaking changes section (always first)
Breaking changes must appear at the top of every release note, even if they are few or minor. The section should include: what changed (the old behavior and the new behavior), why it changed (brief rationale — developers are more accepting of breaking changes when they understand the reason), the exact code change required (old code and new code side by side), and the deprecation timeline if the breaking change was previously deprecated.
## Breaking Changes ### `createSession()` now requires `userId` parameter **Old behavior:** `createSession({ token: 'abc' })` — userId was optional, defaulted to anonymous **New behavior:** `createSession({ token: 'abc', userId: 'user_123' })` — userId is required **Why:** Anonymous sessions were causing data consistency issues in multi-tenant environments. **Migration:** ```diff - const session = await client.createSession({ token: apiToken }) + const session = await client.createSession({ token: apiToken, userId: currentUser.id }) ``` **Deprecation history:** `userId` was deprecated as optional in v3.8.0 (Nov 2024). This version removes the optional behavior.
Tips
- Use a diff block (```diff) for every breaking change — showing old and new code side by side is the fastest way to communicate the required migration
- Include the version when the behavior was first deprecated — this gives developers context for how long they have had to migrate
- If there are zero breaking changes in a release, still include the section with "No breaking changes in this release" — this explicit confirmation is what developers are looking for
API changelog
Document all API changes in structured, predictable format: new endpoints with full request/response schemas, modified endpoints with the exact fields that changed, deprecated endpoints with removal dates and migration targets, and new error codes with descriptions and example responses. Include working code examples for new endpoints.
## API Changes ### New: `POST /v2/batches` Submit multiple operations in a single API call. Reduces round trips for bulk operations. **Request:** ```json {"operations": [{"type": "create", "data": {...}}, {"type": "update", "id": "123", "data": {...}}]} ``` **Response:** `{"batch_id": "batch_abc", "status": "processing", "results_url": "/v2/batches/batch_abc/results"}` ### Modified: `GET /v2/users` - **Added field:** `last_active_at` (ISO 8601 timestamp) — when the user last made an API call - **Field renamed:** `created` → `created_at` (backward compatible — old field name still works until v5.0) ### Deprecated: `GET /v1/users` (removal: 2026-01-15) Migrate to `GET /v2/users`. [Migration guide](https://docs.example.com/migrations/v1-to-v2)
Tips
- Always include a code example for new endpoints — "what does a request look like?" is the first question developers ask
- For modified endpoints: clearly distinguish between additive changes (new fields — non-breaking) and behavioral changes (field renamed, validation changed — potentially breaking)
- Deprecation notices should include the exact removal date, the migration target, and a link to the migration guide — never just "this will be removed in a future version"
SDK and library updates
List version bumps for each official SDK with upgrade commands and language-specific migration notes. If an SDK update includes language-specific breaking changes beyond what the API introduced, list them separately under the SDK. Include the minimum supported runtime version for each SDK.
## SDK Updates | SDK | New version | Previous version | Upgrade | |---|---|---|---| | Node.js / TypeScript | v4.2.0 | v4.1.0 | `npm install @acme/sdk@4.2.0` | | Python | v4.2.0 | v4.1.0 | `pip install acme-sdk==4.2.0` | | Go | v4.2.0 | v4.1.0 | `go get github.com/acme/sdk@v4.2.0` | | Ruby | v4.2.0 | v4.1.0 | `gem update acme-sdk` | **Python-specific note:** The `AsyncClient` class has been renamed to `AsyncAcmeClient` in v4.2.0 to avoid namespace conflicts. The old name still works with a deprecation warning until v5.0. **Minimum supported runtimes:** Node.js 18+, Python 3.10+, Go 1.21+, Ruby 3.1+
Tips
- List every supported SDK, not just the ones that changed — developers want to know that their SDK was reviewed even if it did not change
- Language-specific breaking changes should be listed separately under the SDK section — do not bury them in the API breaking changes section where Python developers might miss them
- Include the minimum supported runtime version with every SDK update — runtime version requirements change over time and have caused production incidents when not communicated
New features and capabilities
After breaking changes and API changelog, list new features with code examples. Developer tool new features should always include a working code example — not just a description. Include performance improvements with quantified numbers and links to benchmarks.
## New Features ### Automatic retry with exponential backoff The SDK now automatically retries failed requests with exponential backoff. Configure via the client options: ```javascript const client = new AcmeClient({ maxRetries: 3, // default: 3 retryDelay: 1000, // base delay in ms, default: 1000 retryOn: [429, 500, 502, 503], // HTTP status codes to retry on }) ``` Disable retries: `{ maxRetries: 0 }` ### Request tracing (beta) All API requests now include an `X-Trace-Id` header in the response. Use this ID when contacting support — it allows us to pull the exact request logs instantly. ## Performance Improvements - SDK initialization time: 45% faster (was 380ms, now 210ms on cold start) - `listUsers()` with 1,000+ records: memory usage reduced by 60%
Tips
- Every new feature needs a working code example — "added X capability" with no code is not useful for developer audiences
- For beta features: clearly label them and document the feedback mechanism — developers need to know what "beta" means for production use
- Performance improvements with quantified numbers are high-credibility signals for developer audiences — show the before and after numbers
Bug fixes and known issues
List bug fixes with the error condition (not the internal implementation cause), issue numbers that link to GitHub issues or your bug tracker, and the affected versions. If a bug was reported by a community member, crediting them builds goodwill. Known issues that are not yet fixed should be listed with workarounds.
## Bug Fixes - Fixed: `pagination.nextCursor` returned `undefined` instead of `null` when there were no more results ([#1247](https://github.com/acme/sdk/issues/1247)). Reported by @developer-name. - Fixed: SDK threw an uncaught exception when the API returned a 503 with an empty response body. Now handles gracefully and retries. - Fixed: TypeScript types for `WebhookEvent` were missing the `metadata` field that was added in v4.1.0. ## Known Issues - Streaming responses in Python on Windows environments may buffer incorrectly. Workaround: set `stream=False` and use polling instead. Fix targeted for v4.3.0.
Tips
- Link to GitHub issues or your public bug tracker for every bug fix — this closes the loop for developers who reported the issue
- Include affected versions range for each bug fix: "affected v4.0.0–v4.1.9" helps developers know whether their pinned version is affected
- Known issues sections are a trust signal — admitting known issues with workarounds is more respected than pretending they do not exist
Copy-paste template
# [Tool Name] v[X.Y.Z] Release Notes
*Released: [Date] | [Full changelog](link) | [Migration guide](link)*
---
## Breaking Changes
*No breaking changes in this release.* ← Replace with actual changes or keep this line if none.
### [Change name]
**Old behavior:** [Description]
**New behavior:** [Description]
**Why:** [Brief rationale]
```diff
- [old code]
+ [new code]
```
**Deprecated since:** v[X.Y.Z] ([Month Year])
---
## API Changes
### New: `[HTTP METHOD] [/path/to/endpoint]`
[What it does and when to use it]
```json
// Request
{ "[field]": "[value]" }
// Response (200)
{ "[field]": "[value]" }
```
### Modified: `[HTTP METHOD] [/path]`
- **Added:** `[field_name]` ([type]) — [description]
- **Changed:** `[field_name]` — [old behavior] → [new behavior]
### Deprecated: `[HTTP METHOD] [/path]` (removal: [date])
Migrate to `[HTTP METHOD] [/new/path]`. [Migration guide](link).
---
## SDK Updates
| SDK | New version | Previous version | Upgrade command |
|---|---|---|---|
| Node.js / TypeScript | v[X.Y.Z] | v[X.Y.Z] | `npm install @tool/sdk@X.Y.Z` |
| Python | v[X.Y.Z] | v[X.Y.Z] | `pip install tool-sdk==X.Y.Z` |
| Go | v[X.Y.Z] | v[X.Y.Z] | `go get github.com/tool/sdk@vX.Y.Z` |
| Ruby | v[X.Y.Z] | v[X.Y.Z] | `gem install tool-sdk -v X.Y.Z` |
**Minimum supported runtimes:** Node.js [18]+, Python [3.10]+, Go [1.21]+
*Language-specific changes:*
- **[Language]:** [Description of language-specific change with code example if needed]
---
## New Features
### [Feature name]
[One paragraph description of what it does and when to use it.]
```[language]
// Code example showing how to use the feature
```
---
## Bug Fixes
- Fixed: [What was broken — user-facing description]. ([#issue-number](link)) *Reported by @username.*
- Fixed: [What was broken].
## Known Issues
- [Issue description] — Workaround: [Workaround]. Fix targeted for v[X.Y.Z].
---
*Upgrade questions? [Join our Discord](link) or [open a GitHub Discussion](link).*Frequently asked questions
Generate instead of filling in templates
Connect your tools, and Vantage generates the content using real product data. Free to start.
Free to start. No credit card required.