# 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.