deprecation-and-migration
Plan or implement a safe API, feature, data, or schema migration. Use when retiring a live contract; not for ordinary code cleanup.
SKILL.mdagent-plugins/skills/deprecation-and-migration/SKILL.md
GitHubDeprecation and Migration
Move consumers from an existing contract to a replacement without assuming removal is safe. Adapted from Addy Osmani's deprecation-and-migration workflow; see the bundled license and repository third-party notice.
Route precisely
- Use for replacing or retiring a live API, feature, dependency, stored shape, or database schema with possible consumers.
- Use
code-simplificationfor behavior-preserving local refactors andcode-reviewfor a read-only diff review. Usevet-dependencywhen the central decision is whether a replacement package meets the project's contract. - A request for a plan permits planning and read-only inspection; execution of destructive or external steps follows the user's authorization and repository rules.
Inventory the contract
- Read repository instructions, current state, migration history, deployment topology, and declared compatibility promises.
- Identify producers, consumers, stored data, public routes or symbols, operational jobs, and usage evidence. Search plausible alternate paths before declaring a consumer absent. Mark inaccessible downstream consumers unknown.
- State what the replacement preserves, changes, or intentionally drops. Identify whether old and new versions must coexist during rollout.
Design the transition
- Choose phases that keep each deployed combination valid. For schemas, consider expand, backfill, switch readers and writers, then contract; use a different sequence when the actual datastore or deployment model requires it.
- Define migration and validation for existing data, idempotency and restart behavior for backfills, and failure recovery. A down migration is useful only when it can safely restore the previous contract; otherwise specify forward recovery and the point of no return.
- Define notices or migration instructions for affected consumers and a measurable removal gate. Do not equate a zero-result repository search with zero external use.
- Separate destructive removal from the replacement rollout when coexistence or rollback requires it. Verify the resolved target and ownership before any deletion or move.
Published Go modules, when applicable
For published Go modules, inventory exported symbols, interface implementations, import paths, required Go versions, and observable error/serialization behavior. Adding a method to an exported interface can break downstream implementations; a local green build is insufficient. Account for semantic import versioning and path-specific exceptions when planning a new major module. Check the published artifact without relying on local replace directives or workspace state. An existing version-pinned API compatibility tool can supplement consumer evidence but does not prove behavioral compatibility. Published tags must remain immutable; a retraction advises module tooling about a bad version rather than deleting cached copies or migrating users automatically. Keep tagging, pushing, and GoReleaser publication outside a planning or inspection request.
These Go compatibility checks adapt spf13's release guidance, under the bundled LICENSE.spf13-go-skills.
Verify and report
Test or inspect the old/new compatibility combinations that actually occur in deployment. Record the consumer inventory, phase sequence, data and rollback evidence, tests run, removal condition, and unresolved external dependencies. Do not claim the migration is complete until the observed consumer and data conditions meet the stated gate.