mirror of https://github.com/vllm-project/vllm.git
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.
|