From 56d64fbe3026b5ccef9cf9c7f069cd0e892df155 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Tue, 29 Apr 2025 13:29:44 -0400 Subject: [PATCH] [Docs] Propose a deprecation policy for the project (#17063) Signed-off-by: Russell Bryant Co-authored-by: Cyrus Leung --- .../source/contributing/deprecation_policy.md | 87 +++++++++++++++++++ docs/source/design/v1/metrics.md | 3 + docs/source/index.md | 1 + 3 files changed, 91 insertions(+) create mode 100644 docs/source/contributing/deprecation_policy.md diff --git a/docs/source/contributing/deprecation_policy.md b/docs/source/contributing/deprecation_policy.md new file mode 100644 index 0000000000000..598f1612d3af3 --- /dev/null +++ b/docs/source/contributing/deprecation_policy.md @@ -0,0 +1,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. diff --git a/docs/source/design/v1/metrics.md b/docs/source/design/v1/metrics.md index 3f96290798a33..7e7c8b925e21d 100644 --- a/docs/source/design/v1/metrics.md +++ b/docs/source/design/v1/metrics.md @@ -467,6 +467,9 @@ In general: hatch](https://kubernetes.io/docs/concepts/cluster-administration/system-metrics/#show-hidden-metrics) for some time before deleting them. +See the [deprecation policy](project:../../contributing/deprecation_policy.md) for +the project-wide deprecation policy. + ### Unimplemented - `vllm:tokens_total` Added by , but apparently never implemented. This can just be diff --git a/docs/source/index.md b/docs/source/index.md index 43b330e4b432e..56ff7a485f58d 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -181,6 +181,7 @@ design/v1/metrics :maxdepth: 2 contributing/overview +contributing/deprecation_policy contributing/profiling/profiling_index contributing/dockerfile/dockerfile contributing/model/index