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 组件中的重大变更，并且不应对稳定性有任何期望。 |
否 |
是 |