A high-throughput and memory-efficient inference and serving engine for LLMs
Mirrored from https://github.com/tduncan-lum/Nvidia-Optimization-Stack---VLLM.git
Synced Nov 15, 12:15 UTC
[Docs] Propose a deprecation policy for the project (#17063)
Signed-off-by: Russell Bryant <rbryant@redhat.com> Co-authored-by: Cyrus Leung <cyrus.tl.leung@gmail.com>
Russell Bryant committed
Apr 29, 2025 at 13:29 UTC
56d64fbe3026b5ccef9cf9c7f069cd0e892df155
3 files changed
+91
docs/source/contributing/deprecation_policy.md
new
+87
@@ -0,0 +1,87 @@
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.
docs/source/design/v1/metrics.md
+3
@@ -467,6 +467,9 @@ In general:
467
hatch](https://kubernetes.io/docs/concepts/cluster-administration/system-metrics/#show-hidden-metrics)
468
for some time before deleting them.
469
470
+See the [deprecation policy](project:../../contributing/deprecation_policy.md) for
471
+the project-wide deprecation policy.
472
+
473
### Unimplemented - `vllm:tokens_total`
474
475
Added by <gh-pr:4464>, but apparently never implemented. This can just be
docs/source/index.md
+1
@@ -181,6 +181,7 @@ design/v1/metrics
181
:maxdepth: 2
182
183
contributing/overview
184
+contributing/deprecation_policy
185
contributing/profiling/profiling_index
186
contributing/dockerfile/dockerfile
187
contributing/model/index