API 政策#
Ray API 指的是类、类方法或函数。当我们声明一个 API 时，我们向用户承诺，他们可以使用这些 API 来开发他们的应用程序，而不必担心这些接口在不同 Ray 版本之间的变化。声明或弃用一个 API 对社区有重大影响。本文档提出了简单的政策，以确保 Ray 贡献者对这些承诺负责，并管理用户的期望。
关于API的暴露级别，请参阅 API稳定性。
API 文档策略#
文档是我们向用户展示API的主要渠道之一。如果我们提供的信息不正确，可能会显著影响用户应用程序的可靠性和可维护性。根据API的暴露级别，以下是确保我们信息准确性的政策。
政策/暴露级别 |
稳定的公共API |
Beta 公共 API |
Alpha 公共 API |
已弃用 |
开发者 API |
|---|---|---|---|---|---|
这个API必须被文档化吗？ |
是 |
是 |
是 |
是 |
由开发者决定 |
方法必须使用其中一个API注解（PublicAPI、DeveloperAPI或Deprecated）进行注解吗？ |
是 |
是 |
是 |
是 |
不。缺少注释意味着默认情况下为开发者API级别。 |
这个API可以是私有的（要么在_internal模块内，要么有下划线前缀）吗？ |
不 |
不 |
不 |
不 |
不 |
API 生命周期策略#
用户对某些暴露级别的期望很高，因此我们在不同级别之间移动API时需要谨慎。以下是管理API暴露生命周期的政策。
政策/暴露级别 |
稳定的公共API |
Beta 公共 API |
Alpha 公共 API |
已弃用的API |
开发者 API |
|---|---|---|---|---|---|
这个API可以在没有任何警告的情况下提升到更高级别，并向用户发出提醒吗？ |
是 |
是 |
是 |
不 |
是 |
这个API可以降级到较低的级别吗？如果是，那么如何操作？ |
只能降级为已弃用。API 应发出警告信息，并在 6个月（或+25个ray次要版本） 内设定弃用期限。 |
只能降级为已弃用。API 应发出警告信息，并在 3 个月（或 +12 个 ray 次要版本） 内设定弃用截止日期。 |
用户必须允许并预期alpha组件中的重大变更，并且不得对稳定性有任何期望。 |
是 |
没有注解意味着它默认是一个开发者API |
你能移除或更改此API的参数吗？ |
是的。API 应该发出警告信息，并且你必须为原始版本的寿命终止设定一个截止日期，即 6个月或+25个Ray次要版本。在过渡期间，你必须同时支持新旧参数。 |
是的。API 应该发出警告信息，并且你必须为更改设置一个截止日期，即 3个月或+12个Ray次要版本。在过渡期间，你必须同时支持新旧参数。 |
用户必须允许并预期alpha组件中的重大变更，并且不得对稳定性有任何期望。 |
不 |
是 |