弃用策略¶

本文档概述了 vLLM 项目中弃用功能的官方策略和流程。

概述¶

vLLM 使用结构化的“弃用流程”来指导已弃用功能的生命周期。该策略确保用户在功能被弃用时能获得清晰且充分的通知，并以一致且可预测的方式进行弃用。

我们的目标是在持续创新和尊重用户对现有功能的依赖之间取得平衡。弃用与我们的**次要 (Y) 版本**相关联，遵循语义化版本控制 (X.Y.Z)，其中

X 是主版本号（不常变）
Y 是次要版本号（用于重大更改，包括弃用/移除）
Z 是补丁版本号（用于修复和更安全的增强）

受此策略约束的功能至少包括以下内容：

命令行标志
环境变量
配置文件
OpenAI 兼容 API 服务器中的 API
vllm 库的公共 Python API

弃用流程¶

弃用过程包含多个清晰定义的阶段，这些阶段跨越多个 Y 版本。

1. 已弃用（默认启用）¶

操作：功能被标记为已弃用。
时间线：移除版本会在弃用警告中明确说明（例如，“此功能将在 v0.10.0 中移除”）。
沟通：在以下位置注明弃用情况（如适用）：
- 帮助字符串
- 日志输出
- API 响应
- /metrics 输出（针对指标功能）
- 面向用户的文档
- 发布说明
- GitHub Issue（RFC）用于反馈
- 使用 @typing_extensions.deprecated 装饰器记录 Python API。

2. 已弃用（默认禁用）¶

操作：功能默认禁用，但仍可通过命令行标志或环境变量重新启用。使用该功能而不重新启用将抛出错误。
目的：允许那些错过先前警告的用户暂时回退，同时表明即将移除。确保任何剩余的使用情况都被明确暴露，并在完全移除之前阻止静默性故障。

3. 已移除¶

操作：功能已从代码库中完全移除。
注意：只有经过先前弃用阶段的功能才会被移除。

示例时间线¶

假设一个功能在 v0.9.0 中被弃用。

发布	状态
`v0.9.0`	功能被弃用，并列出明确的移除版本。
`v0.10.0`	功能现在默认禁用，使用时会抛出错误，但可通过重新启用来支持旧版使用。
`v0.11.0`	功能已移除。

重要指南¶

补丁版本中禁止移除：不允许在补丁 (.Z) 版本中移除已弃用功能，以避免对用户造成意外。
现有弃用的宽限期：任何**在此策略发布之前**被弃用的功能，其宽限期将从**现在**开始计算，而不是追溯计算。
文档至关重要：确保用户能清晰地记录流程的每个阶段。

最终说明¶

本策略是一个活文档，可能会随着项目及其用户需求的变化而演变。我们欢迎并鼓励在完善流程时获得社区的反馈。