skills.rest
0xMuluh
0xMuluhCOMMUNITY
Explore all skills by this author →
GitHub

deprecate-and-replace

Plan and execute API deprecations with canonical replacements, delegation, and migration guidance.

1|Updated Aug 11, 2026
Search Tags:#code maintenance#deprecation#semantic versioning#backward compatibility#r package#api migration#function rename
One-click install
npx skills add https://github.com/0xMuluh/package-development-skills --skill deprecate-and-replace-0xmuluh
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: deprecate-and-replace
Source: https://github.com/0xMuluh/package-development-skills/tree/main/deprecate-and-replace
Command: npx skills add https://github.com/0xMuluh/package-development-skills --skill deprecate-and-replace-0xmuluh

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Retiring a public API, argument, behavior, or package location without breaking existing users is hard: vague warnings, duplicated implementations, and premature removals cause downstream breakage. This Skill provides a structured deprecation workflow that keeps old interfaces working as thin compatibility layers while guiding users to a canonical replacement. ## Core Features & Use Cases - Structured Deprecation Planning: Requires an explicit deprecation statement covering the old interface, canonical replacement, reason, transition behavior, migration path, and removal policy before any code changes. - Delegation-Based Compatibility: Guides you to keep one canonical implementation and turn deprecated functions or arguments into thin wrappers that warn and delegate, covering function renames, argument renames, moved functionality, and return-format changes. - Transition Testing and Documentation: Ensures the deprecated path preserves behavior, internal callers migrate to the replacement, documentation teaches the new API, and removal happens as a separate change per project policy. - Use Case: When renaming getRDA() to getJointRDA() in an R package, use this Skill to create a warning wrapper that delegates to the new function, update docs and NEWS, migrate internal callers, and schedule removal for a later release. ## Quick Start Ask the AI to deprecate an old function or argument in favor of its replacement while preserving behavior and emitting a clear migration warning.

Frequently Asked Questions about deprecate-and-replace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I deprecate a function without breaking existing users?▼

Keep the old function as a thin wrapper that emits a deprecation warning naming the replacement and then delegates to the new canonical implementation. This preserves behavior during the transition while maintaining only one code path, and removal happens later as a separate change.

How to rename a function argument in an R package safely?▼

Accept the new argument name, accept the old name with a deprecation signal, and error clearly on conflicting simultaneous values. Map the old argument to the new semantics and document only the new name in primary examples so the two names never drift into different behavior.

When should a deprecated API be removed?▼

Removal should follow project policy, semantic versioning rules, and ecosystem release cadence rather than an arbitrary schedule. Common strategies are removing after one or more releases or at the next major version, always as a separate change from the deprecation itself.

Should I keep a permanent alias instead of deprecating the old name?▼

A permanent alias is appropriate only when both names are established standards or interoperability requires both, with negligible maintenance cost. Otherwise prefer one canonical name with a temporary deprecated alias, since permanent synonyms expand the conceptual surface of the API.

What are the limitations of deprecating across package boundaries?▼

Delegating from a source package to a destination package can create undesirable dependency directions or cycles. Alternatives include re-exports during transition, lightweight local compatibility, coordinated releases, or removal at a major version boundary.

Related Skills

Explore More Software Engineering Skills→
dbc-oduffydbc-oduffy
5

shape

Restate a PM problem into a falsifiable, ratified problem-set artifact.

Community
Intermediate
Comfy-OrgComfy-Org
2.0k

adding-deprecation-warnings

Adds backward-compatible deprecation warnings for renamed or removed TypeScript properties.

Official
Intermediate
cursorcursor
6.6k

principle-migrate-callers-then-delete-legacy-apis

Migrate internal callers to a new API and delete the legacy API in one refactor wave.

Official
Basic
udecodeudecode
240

workflows-compound

Alias the deprecated /workflows:compound command to /ce:compound.

Official
Basic