Create release notes and product updates that developers actually read and care about. This skill covers changelog formatting, versioning communication, breaking change announcements, deprecation notices, and building anticipation for new features. Trigger phrases: "changelog",...
Create release notes and product updates that developers actually read and care about. This skill covers changelog formatting, versioning communication, breaking change announcements, deprecation notices, and building anticipation for new features. Trigger phrases: "changelog",...
Changelogs and Product Updates Developers Care About
When to Use
Use this skill when you need create release notes and product updates that developers actually read and care about. This skill covers changelog formatting, versioning communication, breaking change announcements, deprecation notices, and building anticipation for new features. Trigger phrases: "changelog",...
Release notes are developer communication, not documentation. When done well, they build trust, demonstrate momentum, and turn updates into marketing moments.
Overview
Changelogs serve multiple audiences and purposes:
Active developers: "What changed that affects my integration?"
Evaluating developers: "Is this product actively maintained?"
Developer advocates: "What's worth sharing with my audience?"
Your team: Historical record of what shipped and when
This skill covers creating changelogs that inform, build trust, and occasionally delight.
Before You Start
Review the developer-audience-context skill to understand:
How do your developers prefer to receive updates?
What changes do they care most about?
How much detail do they need?
What's their tolerance for breaking changes?
Your changelog tone and detail level should match your audience.
Changelog Format
The Standard 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- New feature in development
## [2.3.0] - 2024-01-15### Added- New `analyze()` method for sentiment analysis
- Support for batch processing up to 100 items
### Changed- Improved error messages with troubleshooting links
- Default timeout increased from 30s to 60s
### Deprecated
will be removed in v3.0.0
Race condition in concurrent requests (#234)
Memory leak when processing large files (#256)
Critical security patch for authentication bypass
...
-
`old_analyze()`
### Fixed
-
-
## [2.2.1] - 2024-01-08
### Fixed
-
## [2.2.0] - 2024-01-01
Change Categories
Category
Use For
Added
New features, new endpoints, new parameters
Changed
Behavior changes, performance improvements
Deprecated
Features being phased out (still working)
Removed
Features that no longer exist
Fixed
Bug fixes
Security
Security-related changes
Good vs. Bad Entries
Good Changelog Entries:
### Added- New `batch_analyze()` method processes up to 100 items in a single
request, reducing API calls by 90% for bulk operations.
[See docs](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link) (#198)
### Fixed- Fixed timeout errors when processing files larger than 10MB.
Uploads now stream in chunks, eliminating memory issues. (#234)
### Deprecated-`legacy_auth()` will be removed in v3.0.0 (scheduled for March 2024).
Migrate to `oauth_auth()` using our [migration guide](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link).
Bad Changelog Entries:
### Added- New feature
### Fixed- Fixed bug
- Fixed another bug
- Various improvements
### Changed- Updated dependencies
Writing Style
Be specific:
❌ "Improved performance"
✅ "Reduced API response time by 40% for list operations"
Include context:
❌ "Fixed issue #234"
✅ "Fixed timeout errors when uploading large files (#234)"
Link to resources:
✅ "New batch API - [documentation](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link) | [migration guide](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)"
Explain impact:
✅ "Breaking: `user_id` parameter renamed to `id`.
Update your code before upgrading."
What to Include
Always Include
API Changes:
New endpoints
New parameters
Changed response formats
Changed error codes
SDK Changes:
New methods
Changed method signatures
New configuration options
Breaking Changes:
Anything that requires code changes
Removed features
Changed defaults
Security Fixes:
Even if vague, acknowledge security updates
Follow responsible disclosure timeline
Consider Including
Performance Improvements:
### Changed- List operations now 3x faster through pagination optimization
Developer Experience:
### Added- Error messages now include troubleshooting links
- SDK now validates API keys at initialization
Infrastructure:
### Changed- New data center in EU (eu-west.api.example.com)
- Increased rate limits from 100 to 500 requests/minute
Skip or Minimize
Internal refactoring:
❌ "Refactored authentication module"
(unless it affects developers)
Minor dependency updates:
❌ "Updated lodash from 4.17.20 to 4.17.21"
(unless security-related)
Typo fixes:
❌ "Fixed typo in error message"
(batch these into "Various documentation improvements")
Versioning Communication
Semantic Versioning Explained to Users
Help developers understand what version numbers mean:
# Versioning
We follow [Semantic Versioning](https://semver.org/):
-**Major versions (3.0.0)**: May include breaking changes.
Check the migration guide before upgrading.
-**Minor versions (2.3.0)**: New features, backward compatible.
Safe to upgrade.
-**Patch versions (2.3.1)**: Bug fixes only.
Always safe to upgrade.
Version Pinning Guidance
Help developers make good choices:
# Recommended Version Constraints
For stability, we recommend:
-`"myapi": "^2.3.0"` - Get patches and minor updates
-`"myapi": "~2.3.0"` - Get patches only
For production systems:
- Pin exact versions: `"myapi": "2.3.0"`- Review changelogs before upgrading
- Test in staging first
API Versioning Communication
# API Versions## Current Versions-**v2** (current): Full support, recommended for new integrations
-**v1** (legacy): Security fixes only, sunset March 2025
## Version Lifecycle
| Status | Duration | What It Means |
|--------|----------|---------------|
| Current | Ongoing | Full support, new features |
| Legacy | 12 months | Security fixes only |
| Deprecated | 6 months | No updates, migration required |
| Sunset | - | No longer available |
## Specifying Version```bash
curl https://api.example.com/v2/users
# or
curl -H "API-Version: 2024-01-15" https://api.example.com/users
## Breaking Changes
### Breaking Change Announcement Template
```markdown
# Breaking Change: [Brief Description]
**Affects**: SDK v3.0.0, API version 2024-03
**Timeline**: Changes take effect March 15, 2024
## What's Changing
[Clear description of the change]
## Why We're Making This Change
[Honest explanation - better performance, security, consistency]
## Who's Affected
- ✅ Users of SDK v2.x - no action required
- ⚠️ Users of SDK v3.0.0+ - update required
- ⚠️ Direct API users on v1 - update required
## Required Actions
### If you use our SDK:
```python
# Before (v2.x)
client.old_method(user_id="123")
# After (v3.x)
client.new_method(id="123")
If you call the API directly:
# Before
POST /v1/users/123/analyze
# After
POST /v2/users/123/analyze
6 months before: Announce upcoming change
3 months before: Release new version with migration path
1 month before: Send direct emails to affected users
2 weeks before: Final reminder
Day of: Change takes effect
1 week after: Follow-up for stragglers
## Deprecation Notices
### In-Code Deprecation
```python
import warnings
def old_method(self, user_id):
"""
.. deprecated:: 2.3.0
Use :meth:`new_method` instead. Will be removed in v3.0.0.
"""
warnings.warn(
"old_method() is deprecated and will be removed in v3.0.0. "
"Use new_method() instead. "
"Migration guide: https://docs.example.com/migrate-v3",
DeprecationWarning,
stacklevel=2
)
return self.new_method(id=user_id)
### Deprecated-**`/v1/analyze` endpoint**: Use `/v2/analyze` instead.
- Migration guide: [link]
- Sunset date: March 15, 2025
- After sunset: Requests will return 410 Gone
Building Anticipation
"Coming Soon" Announcements
Build excitement for upcoming features:
# Coming in Q2 2024## Batch Processing API (Beta available now)
Process up to 1,000 items in a single request.
[Join the beta](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
## Python SDK v3.0
Complete rewrite with async support, type hints, and 50% faster.
[Preview documentation](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
## EU Data Residency
For customers with European data requirements.
[Join waitlist](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
Release Cadence Communication
Set expectations:
# Release Schedule**SDK Releases**: First Monday of each month
**API Updates**: Continuous (backward compatible)
**Breaking Changes**: Twice per year (March, September)
Subscribe to updates:
- [GitHub releases](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
- [Email newsletter](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
- [Discord announcements](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
- [Twitter/X](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
Feature Launches as Events
Turn significant releases into moments:
# 🚀 SDK v3.0 Launch
We're excited to announce the biggest SDK update in 2 years!
## Highlights-**50% faster** request processing
-**Full async support** for high-throughput applications
-**Type hints** throughout for better IDE support
-**Simplified auth** - configure once, use everywhere
## Launch Week-**Monday**: SDK v3.0 stable release
-**Tuesday**: Live coding session (YouTube)
-**Wednesday**: Migration office hours
-**Thursday**: Community showcase
-**Friday**: AMA with the SDK team
## Resources- [Documentation](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
- [Migration guide](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
- [Video walkthrough](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/changelog-updates/link)
## Thank You
Special thanks to our 47 beta testers who found 23 bugs
and suggested 12 improvements that made it into this release!
Distribution Channels
Where to Publish
Channel
Audience
Content Level
GitHub Releases
Developers on repo
Full changelog
Docs changelog
All developers
Full changelog
Blog
Broader audience
Highlights + context
Email
Active users
Summary + action items
Twitter/X
Community
Highlights only
Discord/Slack
Engaged community
Discussion + highlights
Email Templates
Regular Release:
Subject: [Product] v2.3.0 Released - Batch Processing + Bug Fixes
Hey [name],
We just released v2.3.0 with some improvements you'll like:
✨ New batch processing API - handle 100 items at once
🐛 Fixed timeout issues with large files
⚡ 40% faster list operations
Full changelog: [link]
Upgrade guide: [link]
Happy building,
The [Product] Team
Breaking Change:
Subject: ⚠️ Action Required: [Product] Breaking Change on March 15
Hey [name],
We're making changes to improve [X], and you'll need to
update your integration before March 15.
What's changing: [one sentence]
What you need to do: [one sentence]
Full details: [link]
Need help? Reply to this email or join our office hours: [link]
Best,
The [Product] Team
Tools
Changelog Generation
Conventional Commits: Structured commit messages
semantic-release: Automated changelog from commits
changesets: Monorepo changelog management
Keep a Changelog: Format specification
Distribution
GitHub Releases: Native to most developer workflows
