| 1 | # Deprecation Policy |
| 2 | |
| 3 | This document outlines the official policy and process for deprecating features |
| 4 | in the vLLM project. |
| 5 | |
| 6 | ## Overview |
| 7 | |
| 8 | vLLM uses a structured "deprecation pipeline" to guide the lifecycle of |
| 9 | deprecated features. This policy ensures that users are given clear and |
| 10 | sufficient notice when a feature is deprecated and that deprecations proceed in |
| 11 | a consistent and predictable manner. |
| 12 | |
| 13 | We aim to strike a balance between continued innovation and respecting users’ |
| 14 | reliance on existing functionality. Deprecations are tied to our **minor (Y) |
| 15 | releases** following semantic versioning (X.Y.Z), where: |
| 16 | |
| 17 | - **X** is a major version (rare) |
| 18 | - **Y** is a minor version (used for significant changes, including deprecations/removals) |
| 19 | - **Z** is a patch version (used for fixes and safer enhancements) |
| 20 | |
| 21 | Features that fall under this policy include (at a minimum) the following: |
| 22 | |
| 23 | - CLI flags |
| 24 | - Environment variables |
| 25 | - Configuration files |
| 26 | - APIs in the OpenAI-compatible API server |
| 27 | - Public Python APIs for the `vllm` library |
| 28 | |
| 29 | ## Deprecation Pipeline |
| 30 | |
| 31 | The deprecation process consists of several clearly defined stages that span |
| 32 | multiple Y releases: |
| 33 | |
| 34 | ### 1. Deprecated (Still On By Default) |
| 35 | |
| 36 | - **Action**: Feature is marked as deprecated. |
| 37 | - **Timeline**: A removal version is explicitly stated in the deprecation |
| 38 | warning (e.g., "This will be removed in v0.10.0"). |
| 39 | - **Communication**: Deprecation is noted in the following, as applicable: |
| 40 | - Help strings |
| 41 | - Log output |
| 42 | - API responses |
| 43 | - `/metrics` output (for metrics features) |
| 44 | - User-facing documentation |
| 45 | - Release notes |
| 46 | - GitHub Issue (RFC) for feedback |
| 47 | - Documentation and use of the `@typing_extensions.deprecated` decorator for Python APIs |
| 48 | |
| 49 | ### 2. Deprecated (Off By Default) |
| 50 | |
| 51 | - **Action**: Feature is disabled by default, but can still be re-enabled via a |
| 52 | CLI flag or environment variable. Feature throws an error when used without |
| 53 | re-enabling. |
| 54 | - **Purpose**: Allows users who missed earlier warnings a temporary escape hatch |
| 55 | while signaling imminent removal. Ensures any remaining usage is clearly |
| 56 | surfaced and blocks silent breakage before full removal. |
| 57 | |
| 58 | ### 3. Removed |
| 59 | |
| 60 | - **Action**: Feature is completely removed from the codebase. |
| 61 | - **Note**: Only features that have passed through the previous deprecation |
| 62 | stages will be removed. |
| 63 | |
| 64 | ## Example Timeline |
| 65 | |
| 66 | Assume a feature is deprecated in `v0.9.0`. |
| 67 | |
| 68 | | Release | Status | |
| 69 | | ------------- | ----------------------------------------------------------------------------------------------- | |
| 70 | | `v0.9.0` | Feature is deprecated with clear removal version listed. | |
| 71 | | `v0.10.0` | Feature is now off by default, throws an error when used, and can be re-enabled for legacy use. | |
| 72 | | `v0.11.0` | Feature is removed. | |
| 73 | |
| 74 | ## Important Guidelines |
| 75 | |
| 76 | - **No Removals in Patch Releases**: Removing deprecated features in patch |
| 77 | (`.Z`) releases is disallowed to avoid surprising users. |
| 78 | - **Grace Period for Existing Deprecations**: Any feature deprecated **before |
| 79 | this policy** will have its grace period start **now**, not retroactively. |
| 80 | - **Documentation is Critical**: Ensure every stage of the pipeline is |
| 81 | documented clearly for users. |
| 82 | |
| 83 | ## Final Notes |
| 84 | |
| 85 | This policy is a living document and may evolve as the needs of the project and |
| 86 | its users change. Community feedback is welcome and encouraged as we refine the |
| 87 | process. |