As time goes by, some features are deprecated and removed. To avoid deprecations breaking users workflows, the process for the deprecation of features are defined as below.
The plans to deprecate some features should be explicitly noticed. The notice should include by when it will be deprecated, and to where users can ask any related questions including extension of the support. That is, it should include the grace period and ways to claim. If applicable, the notice should also include replacement of the feature.
The notice should be made on FEATURES_DEPRECATION_SCHEDULE.md and USAGE.md. If available, the notice should also be made on execution of the features, and help messages that related to the features. For the notice on the execution, will_be_deprecated() of _damo_deprecation_notice.py can be used.
If the feature is documented on USAGE.md and not explicitly marked as ‘experimental feature’ on the document, the deprecation schedule should provide at least three months of the grace period. In other cases, there is no required minimum grace period. That is, features can be immediately deprecated if those are not documented on USAGE.md or marked as experimental on the document. Users could ask specific features to be officially supported.
Once the grace period is passed and no users' special requests about it have reported, the features are marked as deprecated. The change should again be noticed on FEATURES_DEPRECATION_SCHEDULE.md, USAGE.md, execution output, and help messages as much as possible. For the notice on the execution, deprecated() of _damo_deprecation_notice.py can be used. The notice should include by when the features will be entirely removed from the code base. Unlike deprecations, there is no required minimum grace period for removal of deprecated features.
Once removal grace period is passed, related code can be removed from the source tree. If some of the source code is still required for testing purpose, the code can be moved to _damo_deprecated.py file, and be used by the tests.