API Policy#
Ray APIs refer to classes, class methods, or functions. When we declare an API, we promise our users that they can use these APIs to develop their apps without worrying about changes to these interfaces between different Ray releases. Declaring or deprecating an API has a significant impact on the community. This document proposes simple policies to hold Ray contributors accountable to these promises and manage user expectations.
For API exposure levels, see API Stability.
API documentation policy#
Documentation is one of the main channels through which we expose our APIs to users. If we provide incorrect information, it can significantly impact the reliability and maintainability of our users’ applications. Based on the API exposure level, here is the policy to ensure the accuracy of our information.
Policy/Exposure Level |
Stable Public API |
Beta Public API |
Alpha Public API |
Deprecated |
Developer API |
|---|---|---|---|---|---|
Must this API be documented? |
Yes |
Yes |
Yes |
Yes |
Up to the developers |
Must a method be annotated with one of the API annotations (PublicAPI, DeveloperAPI or Deprecated)? |
Yes |
Yes |
Yes |
Yes |
No. The absence of annotations implies the Developer API level by default. |
Can this API be private (either inside the _internal module or has an underscore prefix)? |
No |
No |
No |
No |
No |
API Lifecycle Policy#
Users have high expectations for certain exposure levels, so we need to be cautious when moving APIs between different levels. Here is the policy for managing the API exposure lifecycle.
Policy/Exposure Level |
Stable Public API |
Beta Public API |
Alpha Public API |
Deprecated API |
Developer API |
|---|---|---|---|---|---|
Can this API be promoted to a higher level without any warnings, heads up to users? |
Yes |
Yes |
Yes |
No |
Yes |
Can this API be demoted to a lower level? If so then how? |
Can be demoted to Deprecated only. The API should emit warning messages and a deadline for deprecations in 6 months (or +25 ray minor versions). |
Can be demoted to Deprecated only. The API should emit warning messages and a deadline for deprecations in 3 months (or +12 ray minor versions). |
Users must allow for and expect breaking changes in alpha components, and must have no expectations of stability. |
Yes |
No annotations mean it is a developer API by default |
Can you remove or change this API’s parameters? |
Yes. The API should emit warning messages and you must set a deadline for the end-of-life of the original version that is 6 months or +25 Ray minor versions. During the transition period, you must support both the new and old parameters. |
Yes. The API should emit warning messages and you must set a deadline for the change in 3 months or +12 Ray minor versions. During the transition period, you must support both the new and old parameters. |
Users must allow for and expect breaking changes in alpha components, and must have no expectations of stability. |
No |
Yes |