From 4ebdf168bb81eb746824c4c018baf53c6b9632ee Mon Sep 17 00:00:00 2001 From: Pietro Date: Mon, 20 Jul 2020 12:11:06 +0200 Subject: [PATCH] docs: deprecation policy --- docs/developer/deprecation.rst | 50 ++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/developer/deprecation.rst diff --git a/docs/developer/deprecation.rst b/docs/developer/deprecation.rst new file mode 100644 index 000000000000..eeb49580f712 --- /dev/null +++ b/docs/developer/deprecation.rst @@ -0,0 +1,50 @@ + +# REST API Deprecation policy + +Tezos is committed to offer a stable and relevant APIs. + +If we intend to discontinue or remove major features from an API, +this will be done gradually in 3 steps: + +| API status | Description + +| Active | The API is live in production. + +| Deprecated | The API is live in production. + | You'll see "Deprecated" next to the API name in the documentation. + | The HTTP header will contain a `Warning 299` + | During the deprecation period, we'll only fix major bugs. + | We'll send a notification announcing that we're deprecating the API. + | We'll decommission the API at the end of the deprecation period. + +| Decommissioned | The API isn't available in production because the deprecation period has ended. + | We won't maintain decommissioned APIs. + +## Timeline + +Deprecations, except in case of a security risk response, are done over the +period of 2 major release. Consider a deprecation happening at a point release +1.1. + +When a RPC call is deprecated, this will be announced in the changelog of a +minor (or major) release, an it's API status will be changed to `Deprecated`. +The API will be available though the entire lifespan of release 1.x and 2.x. + +The API will be decommissioned when releasing version 3.0 . At this point +the API will be not available anymore in production. And it's status demoted +to `Decommissioned`. + +### Deprecation policy. + +- We’ll indicate which API and which API version we’re deprecating. + +- If available, we’ll provide a new API to use instead of the deprecated API. + +- We’ll strive to make our APIs backward-compatible. If an API isn’t + backward-compatible, it’s your responsibility to move to the new API within + the deprecation period specified in our notification. + +- If an API creates a security risk, we may provide less than 30 days’ notice + before making major changes or decommissioning APIs. + + -- GitLab