Deprecation Notices
Comprehensive guide to API deprecation processes, sunset timelines, communication strategies, and graceful migration paths
npx skills add majiayu000/claude-skill-registry --skill deprecation-notices --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Provides a structured, multi-step plan for deprecating an API endpoint, including marking code and docs as deprecated, announcing deprecation via email/blog/changelog, monitoring usage, notifying active users, performing the sunset, and finally removing code. It also covers HTTP headers for deprecation/sunset, OpenAPI/GraphQL/code deprecation examples, and a migration path to a replacement endpoint. It is geared toward API teams managing deprecation timelines and migration processes.
How it works
- Step 1: Mark as Deprecated (Code, Docs) with language-specific examples (JavaScript, Python) and accompanying documentation notes.
- Step 2: Announce (Email, Blog, Changelog) with templates and example messages including sunset dates and migration guidance.
- Step 3: Monitor Usage with metrics tracking, a dashboard example, and usage trends indicating decline.
- Step 4: Reach Out to Active Users by emailing top users and providing migration assistance.
- Step 5: Sunset (Stop Working) by returning 410 Gone and supplying a replacement and migration link.
- Step 6: Remove Code after sunset, with a staged plan (monitor for issues, then delete).
- Deprecation Headers: describes HTTP headers (Deprecation, Sunset, Link, Warning) and a middleware example to attach these headers in Express.
- OpenAPI/GraphQL/Code Deprecation sections give sample annotations and docs to mark deprecated code paths or fields.
- Communication Channels cover in-app banners, emails, blogs, status pages, and release notes.
- Migration Guide outlines how to migrate step-by-step, including updating API calls, handling responses, and testing before deployment.
- Monitoring and Outreach sections describe tracking calls, identifying top users, alerting on spikes, and scheduling migration support.
When to use it
Use this plan when you need a formal, staged approach to deprecating an API endpoint (e.g., /users/:id/profile) and migrate users to a replacement, with defined timelines and communication.
What it can touch
- Not applicable in this summary. The skill references code and docs changes, email templates, dashboards, and OpenAPI/Swagger examples as part of its guidance.
Caveats
- Timeline dates (e.g., 2024-12-31) are examples within the guidance and should be adjusted to actual project schedules.
- The content references general practices and example code snippets for deprecation but does not guarantee outcomes.
- License and tooling notes are from the source repository and not independently verifiable here.
# Deprecation Notices ## What is Deprecation? **Definition:** Announcing end-of-life for an API/feature with time for users to migrate before eventual removal. ### Lifecycle ``` Active → Deprecated → Sunset → Removed Active: Fully supported Deprecated: Still works, but discouraged (6-12 months) Sunset: Stops working Removed: Code deleted ``` ### Example ``` Jan 2024: API v1 active Jun 2024: API v1 deprecated (announce v2) Dec 2024: API v1 sunset (stops working) Jan 2025: API v1 code removed ``` --- ## Why Proper Deprecation Matters ### 1. Avoid Breaking Users Without Warning **Bad:** ``` Deploy new version → Old endpoint removed → Users break immediately → Angry customers → Emergency rollback ``` **Good:** ``` Announce deprecation (6 months notice) → Users migrate gradually → Sunset date arrives → No surprises ``` ### 2. Maintain Trust **Trust Built By:** - Advance notice (6-12 months) - Clear migration path - Support during migration - No surprises **Trust Broken By:** - Sudden changes - No warning - Unclear migration - Breaking without notice ### 3. Smooth Migration **Gradual Migration:** ``` Month 0: Announce deprecation Month 3: 25% migrated Month 6: 50% migrated Month 9: 75% m
- What is Deprecation?
- Lifecycle
- Example
- Why Proper Deprecation Matters
- 1. Avoid Breaking Users Without Warning
- 2. Maintain Trust
- 3. Smooth Migration
- 4. Legal Compliance (If Contractual)
- Deprecation Timeline
- Typical: 6-12 Months for APIs
- Critical Systems: 12-24 Months
- Internal APIs: 3-6 Months
- Consider: Contract Terms, User Base Size
- Deprecation Process
What does the Deprecation Notices skill do?
Comprehensive guide to API deprecation processes, sunset timelines, communication strategies, and graceful migration paths
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill deprecation-notices --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.