88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
|
# Deprecation Policy
|
|||
|
|
|
|||
|
|
This document outlines the official policy and process for deprecating features
|
|||
|
|
in the vLLM project.
|
|||
|
|
|
|||
|
|
## Overview
|
|||
|
|
|
|||
|
|
vLLM uses a structured "deprecation pipeline" to guide the lifecycle of
|
|||
|
|
deprecated features. This policy ensures that users are given clear and
|
|||
|
|
sufficient notice when a feature is deprecated and that deprecations proceed in
|
|||
|
|
a consistent and predictable manner.
|
|||
|
|
|
|||
|
|
We aim to strike a balance between continued innovation and respecting users’
|
|||
|
|
reliance on existing functionality. Deprecations are tied to our **minor (Y)
|
|||
|
|
releases** following semantic versioning (X.Y.Z), where:
|
|||
|
|
|
|||
|
|
- **X** is a major version (rare)
|
|||
|
|
- **Y** is a minor version (used for significant changes, including deprecations/removals)
|
|||
|
|
- **Z** is a patch version (used for fixes and safer enhancements)
|
|||
|
|
|
|||
|
|
Features that fall under this policy include (at a minimum) the following:
|
|||
|
|
|
|||
|
|
- CLI flags
|
|||
|
|
- Environment variables
|
|||
|
|
- Configuration files
|
|||
|
|
- APIs in the OpenAI-compatible API server
|
|||
|
|
- Public Python APIs for the `vllm` library
|
|||
|
|
|
|||
|
|
## Deprecation Pipeline
|
|||
|
|
|
|||
|
|
The deprecation process consists of several clearly defined stages that span
|
|||
|
|
multiple Y releases:
|
|||
|
|
|
|||
|
|
### 1. Deprecated (Still On By Default)
|
|||
|
|
|
|||
|
|
- **Action**: Feature is marked as deprecated.
|
|||
|
|
- **Timeline**: A removal version is explicitly stated in the deprecation
|
|||
|
|
warning (e.g., "This will be removed in v0.10.0").
|
|||
|
|
- **Communication**: Deprecation is noted in the following, as applicable:
|
|||
|
|
- Help strings
|
|||
|
|
- Log output
|
|||
|
|
- API responses
|
|||
|
|
- `/metrics` output (for metrics features)
|
|||
|
|
- User-facing documentation
|
|||
|
|
- Release notes
|
|||
|
|
- GitHub Issue (RFC) for feedback
|
|||
|
|
- Documentation and use of the `@typing_extensions.deprecated` decorator for Python APIs
|
|||
|
|
|
|||
|
|
### 2.Deprecated (Off By Default)
|
|||
|
|
|
|||
|
|
- **Action**: Feature is disabled by default, but can still be re-enabled via a
|
|||
|
|
CLI flag or environment variable. Feature throws an error when used without
|
|||
|
|
re-enabling.
|
|||
|
|
- **Purpose**: Allows users who missed earlier warnings a temporary escape hatch
|
|||
|
|
while signaling imminent removal. Ensures any remaining usage is clearly
|
|||
|
|
surfaced and blocks silent breakage before full removal.
|
|||
|
|
|
|||
|
|
### 3. Removed
|
|||
|
|
|
|||
|
|
- **Action**: Feature is completely removed from the codebase.
|
|||
|
|
- **Note**: Only features that have passed through the previous deprecation
|
|||
|
|
stages will be removed.
|
|||
|
|
|
|||
|
|
## Example Timeline
|
|||
|
|
|
|||
|
|
Assume a feature is deprecated in `v0.9.0`.
|
|||
|
|
|
|||
|
|
| Release | Status |
|
|||
|
|
|---------------|-------------------------------------------------------------------------------------------------|
|
|||
|
|
| `v0.9.0` | Feature is deprecated with clear removal version listed. |
|
|||
|
|
| `v0.10.0` | Feature is now off by default, throws an error when used, and can be re-enabled for legacy use. |
|
|||
|
|
| `v0.11.0` | Feature is removed. |
|
|||
|
|
|
|||
|
|
## Important Guidelines
|
|||
|
|
|
|||
|
|
- **No Removals in Patch Releases**: Removing deprecated features in patch
|
|||
|
|
(`.Z`) releases is disallowed to avoid surprising users.
|
|||
|
|
- **Grace Period for Existing Deprecations**: Any feature deprecated **before
|
|||
|
|
this policy** will have its grace period start **now**, not retroactively.
|
|||
|
|
- **Documentation is Critical**: Ensure every stage of the pipeline is
|
|||
|
|
documented clearly for users.
|
|||
|
|
|
|||
|
|
## Final Notes
|
|||
|
|
|
|||
|
|
This policy is a living document and may evolve as the needs of the project and
|
|||
|
|
its users change. Community feedback is welcome and encouraged as we refine the
|
|||
|
|
process.
|