Marathon has a standardized mechanism by which features are gracefully phased out, and strives to realize the following ideals:
The Deprecation Mechanism is best described by a hypothetical example involving a a plan to remove
our API. The deprecation will be advertised in our release notes, along with the release deprecation schedule.
Hypothetical release notes:
1.5.9 (hypothetical release)
/v2/oldroutehas been marked as deprecated and clients should be updated to use
/v2/routehas the following deprecation schedule:
- 1.5.x -
/v2/oldroutewill continue to function as normal.
- 1.6.x - The API will stop responding to
/v2/oldroute; requests to it will be met with a 404 response. The route can be re-enabled with the command-line argument
- 1.7.x -
/v2/oldrouteis scheduled to be completely removed. If
--deprecated_features=api_oldrouteis still specified, Marathon will refuse to launch, with an error.
As mentioned in the schedule, if Marathon is upgraded to
--deprecated_features=api_oldroute is still
specified, then Marathon will refuse to launch. The expectation is for users to remove their dependence on deprecated
features before they are removed. No state will be migrated if this flag is still specified, making it possible for
the operator to roll-back to the version of Marathon prior to the upgrade, remove the
--deprecated_features=api_oldroute flag, confirm that they no longer depend on it, and then migrate again.