Release Notes Template for Developer Tools
Developer tool release notes serve a different audience than consumer product changelogs. Developers need to know: will this break my integration, do I need to change my code, and what new capabilities are available. Burying a breaking change in a bulleted list of 20 minor improvements creates integration failures and erodes developer trust.
This template structures release notes for developer tools with breaking changes prominently displayed, migration guides included, and SDK/API version information clearly communicated.
Template sections
5 sections covering the complete release notes workflow.
Breaking Changes (Top of Notes)
Breaking changes must appear at the very top of release notes, before any new features or improvements. Each breaking change needs: what changed, why, what breaks, and the migration path. Include code examples showing the old and new patterns. Developers who miss a breaking change will have failing integrations and will blame your documentation.
BREAKING: /api/v2/users endpoint now requires pagination (max 100 per page). Previously returned all users. Why: performance at scale (customers with 50K+ users experienced 30-second response times). What breaks: clients calling GET /users and expecting the full list. Migration: add ?page=1&per_page=100 and implement pagination loop. See migration guide below. Deadline: v2 unpaginated endpoint removed on October 1, 2026.
Tips
- Always put breaking changes at the top with a prominent visual indicator
- Include before/after code examples for every breaking change
- Provide a migration deadline with at least 90 days notice
- Link to a detailed migration guide for complex breaking changes
New Features and Capabilities
Describe new features with immediate utility: what you can do now that you could not before, the API endpoint or SDK method to use, and a working code example. Developers evaluate new features by how quickly they can try them, so include a copy-paste example that works.
NEW: Batch operations API. Process up to 1,000 operations in a single request. Endpoint: POST /api/v2/batch. Use case: bulk user imports, mass status updates. Example: curl -X POST https://api.example.com/v2/batch -d '{"operations": [{"method": "POST", "path": "/users", "body": {"name": "Alice"}}]}'. Response includes individual status for each operation. Rate limit: 10 batch requests per minute. Documentation: /docs/api/batch.
Tips
- Include a working code example for every new feature
- Specify rate limits and quotas for new endpoints
- Link to detailed API documentation for each new feature
- Note which SDK versions include support for the new feature
SDK and Library Updates
Document SDK version updates per language with changelog: new methods, deprecated methods, minimum runtime version requirements, and dependency changes. Developers using your SDK need to know if updating will affect their build or runtime environment.
SDK Updates: Python SDK v3.4.0 (requires Python 3.8+, previously 3.7+). New: batch() method for bulk operations. Deprecated: list_all_users() - use list_users(paginate=True) instead (removal in v4.0). Node.js SDK v5.2.0 (requires Node 18+). New: batchOperations() method. Bug fix: timeout handling in WebSocket connections. Go SDK v2.1.0: new BatchRequest struct, updated protobuf dependency to v1.31.
Tips
- List minimum runtime version changes prominently - these break CI/CD pipelines
- Include deprecated methods with the version where they will be removed
- Note dependency updates that may conflict with customer codebases
- Provide upgrade guides for major SDK version bumps
Deprecation Notices
Deprecation notices should include: what is deprecated, the replacement, the timeline (warning, sunset, removal), and the migration effort estimate. Developers need lead time to plan migration work, so provide at least 6 months notice for significant deprecations and 12 months for API version removals.
DEPRECATED: API v1 endpoints. Sunset date: March 1, 2027 (6 months from now). Replacement: API v2 (available since January 2026). Migration effort: small for most integrations (2-4 hours), large for custom webhook integrations (1-2 days). Migration guide: /docs/migration/v1-to-v2. Support: v1 receives security patches only, no new features. After March 1: v1 endpoints return 410 Gone.
Tips
- Provide at least 6 months deprecation notice for APIs, 12 months for major versions
- Include migration effort estimates so developers can plan capacity
- Continue security patches on deprecated versions until removal
- Use HTTP 410 Gone after removal, not 404, so developers understand the endpoint was removed
Bug Fixes and Performance
List bug fixes and performance improvements with enough detail for affected developers to verify the fix. Include the conditions that triggered the bug and the metric improvement for performance changes. Developers who reported the bug want to know it is fixed; developers who did not want to know if they were affected.
FIXED: WebSocket reconnection failed when server returned 1006 close code during network interruption (reported by 12 customers). Now retries with exponential backoff up to 5 attempts. PERFORMANCE: /api/v2/search p95 latency reduced from 850ms to 320ms for queries with more than 10 filter conditions. Improvement from query plan optimization, no API changes required.
Tips
- Reference the issue number or customer report for bug fixes
- Include the conditions that triggered the bug so developers can verify the fix applies
- Provide before/after metrics for performance improvements
- Note whether API changes are required or if improvements are server-side only
Copy-paste template
# Release Notes — [Product] v[Version] ## Breaking Changes - **[Change]**: [What changed, why, migration path] - Before: `[old code]` - After: `[new code]` - Deadline: [removal date] ## New Features - **[Feature]**: [Description with code example] - Endpoint/Method: [API path or SDK method] - Rate limit: [Limit] - Docs: [Link] ## SDK Updates | Language | Version | Min Runtime | Changes | |---|---|---|---| | [Language] | [Version] | [Runtime] | [Changes] | ## Deprecations | Item | Replacement | Sunset Date | |---|---|---| | [Item] | [Replacement] | [Date] | ## Bug Fixes - [Fix description with trigger conditions]
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.