Removal Process
Sometimes you get public APIs wrong. Sometimes technology radically changes from underneath you and you need to change things. You need a removal process to handle behaviors gracefully exiting from the codebase.
- Software which has already been built may continue to use symbols which have been soft-removed.
- New software is at first warned to stop using behavior
- A later version removes it from the SDK.
Deprecation: An entity is marked as "deprecated." Documentation is adjusted to mention what should be done instead. Warnings are put in place to discourage continuing to use the deprecated entity. Deprecations remain for one or more minor releases.
Soft-removal: An entity is rendered inaccessible in the SDK. Continued use requires using new identifiers that make it painfully obvious you are doing it wrong. Identifiers may be fully removed. Old code continues to work but new code is rendered unable to use the deprecated objects. A soft removal comes with a minor bump of the library's version.
Hard-removal: An entity is removed entirely. It no longer exists in the SDK or the underlying library. A hard removal comes with a major bump of the library's version. A library performing a hard removal will need to keep a fork of the older version around for old software to remain compatible.
Deprecation Time
Generally something being removed should be marked deprecated for one or more releases. Developers need time to hear of the notice, replacement, and make suitable adjustments (if their software is still alive and will be updated.) If dead software needs to be kept around then the users will need to get workarounds in place.
Deprecated code is eventually killed. It may survive in compatibility layers inaccessible to new compiles or it may require a fork of the library to be kept around to run that particular old program.
However, quite some time should pass between marking for deprecation and removal of the features.