Skip to content

GitLab

Switch branch/tag
Find file Normal viewHistoryPermalink
deprecation_policy.md 3.49 KB
Newer Older
raojy's avatar
raw_vllm  
raojy committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87 
# 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.