Dropping Platform or Language Version Support
This playbook guides SDK maintainers through dropping support for a platform or language version in a way that minimizes user disruption. It covers evidence gathering, deprecation announcements, maintenance periods, and eventual removal. By following these steps, users will have clear migration paths and sufficient notice before breaking changes occur.
Related resources:
- Platform/language version support policy — support policy and requirements
- Breaking change process — process for removal in major versions
- Deprecation lifecycle — deprecation timeline
- Deprecating an SDK — when deprecating the entire SDK, not just a platform version
Before proposing to drop support, you MUST gather and document:
- Upstream EOL status: Has the language/platform version reached end of life?
- Usage data: What percentage of users are on this version?
- Maintenance burden: How much effort does supporting this version cost?
This evidence helps stakeholders make informed decisions about the timeline and impact.
In the minor release where support is deprecated, you MUST:
- Add a changelog entry stating which version will be dropped and when
- Update documentation (README, docs site) to reflect the deprecation
- Keep CI testing against the deprecated version during this period
This ensures users have clear warning before breaking changes occur.
You MUST wait at least one full minor release cycle after the deprecation announcement. Users need time to see the deprecation and plan their upgrade path.
When removing support in a major version, you MUST:
- Drop the version from the CI test matrix
- Update documentation (README, docs site) to reflect the removed support
- Include
BREAKING CHANGE:in the commit footer (Breaking change process)
You MUST provide clear migration guidance in the changelog and documentation:
Upgrade to [language/platform] version X.Y or later before upgrading to SDK version N.
This helps users understand the upgrade path and avoid breaking their applications.
- Breaking change process — process for removal in major versions
- Deprecation lifecycle — deprecation timeline requirements
- Platform/language version support policy — support policy baseline
| Version | Date | Summary |
|---|---|---|
1.0.0 | 2026-02-23 | Initial playbook — platform/language version deprecation with evidence requirements and migration guidance |
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").