API Policy#
Ray APIs 指的是类、类方法或函数。当我们声明一个 API 时，我们就向用户承诺，他们可以使用这些 API 来开发他们的应用程序，而无需担心这些接口在不同 Ray 版本之间的更改。声明或弃用 API 对社区有着重大影响。本文档提出了一些简单的政策，以确保 Ray 贡献者能够兑现这些承诺并管理用户预期。
有关 API 暴露级别，请参阅 API Stability。
API 文档政策#
文档是我们向用户暴露 API 的主要渠道之一。如果我们提供不正确的信息，可能会对用户应用程序的可靠性和可维护性产生重大影响。基于 API 暴露级别，以下是确保信息准确性的政策。
Policy/Exposure Level |
Stable Public API |
Beta Public API |
Alpha Public API |
已弃用 |
Developer API |
|---|---|---|---|---|---|
Must this API be documented? |
是 |
是 |
是 |
是 |
Up to the developers |
Must a method be annotated with one of the API annotations (PublicAPI, DeveloperAPI or Deprecated)? |
是 |
是 |
是 |
是 |
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)? |
否 |
否 |
否 |
否 |
否 |
API Lifecycle Policy#
用户对某些暴露级别有着很高的期望，因此我们在移动 API 跨不同级别时需要谨慎。以下是管理 API 暴露生命周期的政策。
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? |
是 |
是 |
是 |
否 |
是 |
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. |
是 |
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. |
否 |
是 |