Package Deprecation

Properly deprecate and sunset packages when they're no longer maintained.

Deprecating a Package

curl -X POST https://registry.yourcompany.com/v1/packages/pkg_ID/deprecate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "This package is deprecated. Use new_package instead.",
    "replacement": "new_package"
  }'

Deprecation Workflow

Announce deprecation - Document in README
Publish deprecation notice - Via API
Provide migration path - Guide users to replacement
Grace period - Allow time for migration (3-6 months)
Final notice - Warn before deletion
Delete - Remove package

Migration Guide Example

# DEPRECATED

This package is deprecated and will be removed on 2025-12-31.

## Migration

Replace `old_package` with `new_package`:

\`\`\`yaml
dependencies:
  # old_package: ^1.0.0  # Remove this
  new_package: ^2.0.0    # Use this instead
\`\`\`

### API Changes

- `OldClass` → `NewClass`
- `oldMethod()` → `newMethod()`

Unpublishing Versions

Remove specific versions:

curl -X DELETE https://registry.yourcompany.com/v1/packages/pkg_ID/versions/1.0.0 \
  -H "Authorization: Bearer YOUR_TOKEN"

Warning: Only unpublish if version has critical security issues.

Deleting Packages

Permanently delete package:

curl -X DELETE https://registry.yourcompany.com/v1/packages/pkg_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Danger: Deletion is permanent and cannot be undone!

Best Practices

Communicate early - Give users advance notice
Provide alternatives - Recommend replacement packages
Migration guide - Document how to migrate
Grace period - Allow time (3-6 months)
Version support - Maintain security fixes during transition

Deprecation Timeline Example

Month 0: Announce deprecation
Month 1: Publish migration guide
Month 3: Stop feature development
Month 6: Stop bug fixes (security only)
Month 12: Delete package

Next Steps

Package Overview - Package lifecycle
Versioning - Version management

On this page