From a6f91f70b7006e17dbf264923531eace0be63a23 Mon Sep 17 00:00:00 2001 From: Yikun Jiang Date: Mon, 17 Feb 2025 14:13:28 +0800 Subject: [PATCH] [Doc] Add versioning_policy doc (#62) ### What this PR does / why we need it? This patch add the versioning policy doc for vllm-ascend Reference: - https://spark.apache.org/versioning-policy.html - https://docs.openstack.org/project-team-guide/stable-branches.html - https://github.com/pytorch/pytorch/blob/main/RELEASE.md ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? preview: https://vllm-ascend--62.org.readthedocs.build/en/62/ Signed-off-by: Yikun Jiang --- README.md | 11 +++- README.zh.md | 11 +++- docs/source/conf.py | 2 +- .../developer_guide/versioning_policy.md | 64 +++++++++++++++++++ .../developer_guide/versioning_policy.zh.md | 64 +++++++++++++++++++ docs/source/index.md | 1 + 6 files changed, 150 insertions(+), 3 deletions(-) create mode 100644 docs/source/developer_guide/versioning_policy.md create mode 100644 docs/source/developer_guide/versioning_policy.zh.md diff --git a/README.md b/README.md index 54a1e9f..0bd2437 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ vLLM Ascend Plugin

-| About Ascend | Developer Slack (#sig-ascend) | +| About Ascend | Documentation | Developer Slack (#sig-ascend) |

@@ -77,6 +77,15 @@ We welcome and value any contributions and collaborations: - Please feel free comments [here](https://github.com/vllm-project/vllm-ascend/issues/19) about your usage of vLLM Ascend Plugin. - Please let us know if you encounter a bug by [filing an issue](https://github.com/vllm-project/vllm-ascend/issues). +## Branch + +vllm-ascend has main branch and dev branch. + +- **main**: main branch，corresponds to the vLLM main branch, and is continuously monitored for quality through Ascend CI. +- **vX.Y.Z-dev**: development branch, created with part of new releases of vLLM. For example, `v0.7.1-dev` is the dev branch for vLLM `v0.7.1` version. + +Please refer to [Versioning policy](docs/source/developer_guide/versioning_policy.md) for more details. + ## License Apache License 2.0, as found in the [LICENSE](./LICENSE) file. diff --git a/README.zh.md b/README.zh.md index 07c3db1..701b556 100644 --- a/README.zh.md +++ b/README.zh.md @@ -10,7 +10,7 @@ vLLM Ascend Plugin

-| 关于昇腾 | 开发者 Slack (#sig-ascend) | +| 关于昇腾 | 官方文档 | 开发者 Slack (#sig-ascend) |

@@ -71,6 +71,15 @@ curl http://localhost:8000/v1/models **请参阅 [官方文档](https://vllm-ascend.readthedocs.io/en/latest/)以获取更多详细信息** +## 分支 + +vllm-ascend有主干分支和开发分支。 + +- **main**: 主干分支，与vLLM的主干分支对应，并通过昇腾CI持续进行质量看护。 +- **vX.Y.Z-dev**: 开发分支，随vLLM部分新版本发布而创建，比如`v0.7.1-dev`是vllm-asend针对vLLM `v0.7.1`版本的开发分支。 + +请参阅[版本策略](docs/source/developer_guide/versioning_policy.zh.md)了解更多详细信息。 + ## 贡献 有关更多详细信息，请参阅 [CONTRIBUTING](docs/source/developer_guide/contributing.zh.md)，可以更详细的帮助您部署开发环境、构建和测试。 diff --git a/docs/source/conf.py b/docs/source/conf.py index c90946f..37aec53 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -78,7 +78,7 @@ exclude_patterns = [ '.venv', 'README.md', # TODO(yikun): Remove this after zh supported - 'developer_guide/contributing.zh.md' + '**/*.zh.md' ] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/source/developer_guide/versioning_policy.md b/docs/source/developer_guide/versioning_policy.md new file mode 100644 index 0000000..b571a93 --- /dev/null +++ b/docs/source/developer_guide/versioning_policy.md @@ -0,0 +1,64 @@ +# Versioning policy + +Starting with vLLM 0.7.x, the vLLM Ascend Plugin ([vllm-project/vllm-ascend](https://github.com/vllm-project/vllm-ascend)) project follows the [PEP 440](https://peps.python.org/pep-0440/) to publish matching with vLLM ([vllm-project/vllm](https://github.com/vllm-project/vllm)). + +## vLLM Ascend Plugin versions + +Each vllm-ascend release will be versioned: `v[major].[minor].[micro][rcN][.postN]` (such as +`v0.7.1rc1`, `v0.7.1`, `v0.7.1.post1`) + +- **Final releases**: will typically be released every **3 months**, will take the vLLM upstream release plan and Ascend software product release plan into comprehensive consideration. +- **Pre releases**: will typically be released **on demand**, ending with rcN, represents the Nth release candidate version, to support early testing by our users prior to a final release. +- **Post releases**: will typically be released **on demand** to support to address minor errors in a final release. It's different from [PEP-440 post release note](https://peps.python.org/pep-0440/#post-releases) suggestion, it will contain actual bug fixes considering that the final release version should be matched strictly with the vLLM final release version (`v[major].[minor].[micro]`). The post version has to be published as a patch version of the final release. + +For example: +- `v0.7.x`: it's the first final release to match the vLLM `v0.7.x` version. +- `v0.7.1rc1`: will be the first pre version of vllm-ascend. +- `v0.7.1.post1`: will be the post release if the `v0.7.1` release has some minor errors. + +## Branch policy + +vllm-ascend has main branch and dev branch. + +- **main**: main branch，corresponds to the vLLM main branch, and is continuously monitored for quality through Ascend CI. +- **vX.Y.Z-dev**: development branch, created with part of new releases of vLLM. For example, `v0.7.1-dev` is the dev branch for vLLM `v0.7.1` version. + +Usually, a commit should be ONLY first merged in the main branch, and then backported to the dev branch to reduce maintenance costs as much as possible. + +### Maintenance branch and EOL: +The branch status will be in one of the following states: + +| Branch | Time frame | Summary | +|-------------------|----------------------------------|----------------------------------------------------------------------| +| Maintained | Approximately 2-3 minor versions | All bugfixes are appropriate. Releases produced, CI commitment. | +| Unmaintained | Community interest driven | All bugfixes are appropriate. No Releases produced, No CI commitment | +| End of Life (EOL) | N/A | Branch no longer accepting changes | + +### Branch state + +Note that vllm-ascend will only be released for a certain vLLM release version rather than all versions. Hence, You might see only part of versions have dev branches (such as only `0.7.1-dev` / `0.7.3-dev` but no `0.7.2-dev`), this is as expected. + +Usually, each minor version of vLLM (such as 0.7) will correspond to a vllm-ascend version branch and support its latest version (for example, we plan to support version 0.7.3) as following shown: + +| Branch | Status | Note | +|-----------|------------|--------------------------------------| +| main | Maintained | CI commitment for vLLM main branch | +| 0.7.1-dev | Maintained | CI commitment for vLLM 0.7.1 version | + +## Release Compatibility Matrix + +Following is the Release Compatibility Matrix for vLLM Ascend Plugin: + +| vllm-ascend | vLLM | Python | Stable CANN | PyTorch/torch_npu | +|--------------|--------------| --- | --- | --- | +| v0.7.x (TBD) | v0.7.x (TBD) | 3.9 - 3.12 | 8.0.0.beta1 | 2.5.1 / 2.5.1rc1 | + +## Release cadence + +### Next final release (`v0.7.x`) window + +| Date | Event | +|---------|-----------| +| February 2025 | Release candidates (RC1), v0.7.1rc1 | +| March 2025 | Release candidates (RC2), v0.7.1rc2 or v0.7.3rc1 | +| March 2025 | Final release passes, match vLLM v0.7.x latest: v0.7.1 or v0.7.3 | diff --git a/docs/source/developer_guide/versioning_policy.zh.md b/docs/source/developer_guide/versioning_policy.zh.md new file mode 100644 index 0000000..7ce6616 --- /dev/null +++ b/docs/source/developer_guide/versioning_policy.zh.md @@ -0,0 +1,64 @@ +# 版本策略 + +从vLLM的0.7.x版本开始，vLLM Ascend Plugin ([vllm-project/vllm-ascend](https://github.com/vllm-project/vllm-ascend)) 整体遵循[PEP 440](https://peps.python.org/pep-0440/)的版本策略，与vLLM ([vllm-project/vllm](https://github.com/vllm-project/vllm)) 配套发布。 + +## vLLM Ascend Plugin版本 + +vllm-ascend的版本号为：`v[major].[minor].[micro][rcN][.postN]`（比如`v0.7.1rc1`, `v0.7.1`, `v0.7.1.post1`） + +- **Final releases （正式版）**: 通常3个月发布一次正式版，将会综合考虑vLLM上游发布及昇腾产品软件发布策略。 +- **Pre releases （尝鲜版）**: 通常为按需发布，以rcN结尾，代表第N个Release Candidate版本，提供在final release之前的尝鲜版（早期试用版）。 +- **Post releases （补丁版）**: 通常在final release发布后按需发布，主要是修复最终版本的错误。这个策略与[PEP-440提到的策略](https://peps.python.org/pep-0440/#post-releases)有所不同，它会包含实际的bug修复，考虑到正式版与vLLM的版本（`v[major].[minor].[micro]`）配套发布。因此，Post releases通常是Final release的补丁版本。 + +例如： +- `v0.7.x`: 是配套 vLLM `v0.7.x` 版本的正式版。 +- `v0.7.1rc1`: 是vllm-ascend第一个尝鲜版（早期试用版）。 +- `v0.7.1.post1`: 是`v0.7.1`版本的post release。 + +## 分支管理策略 + +vllm-ascend有主干和开发两种分支。 + +- **main**: 主干分支，与vLLM的主干分支对应，并通过昇腾CI持续进行质量看护。 +- **vX.Y.Z-dev**: 开发分支，随vLLM部分新版本发布而创建，比如`v0.7.1-dev`是vllm-ascend针对vLLM `v0.7.1`版本的开发分支。 + + +通常，一个commit需要先合入到主干分支，然后再反合到开发分支，从而尽可能地减少版本维护成本。 + + +### 分支维护和EOL +某个分支的状态将会以下三种之一： +| 分支 | 维护时间 | 备注 | +|-------------------|----------------------------|----------------------------------------------------------------------| +| Maintained （维护中） | 大概2-3个minor版本 | 合入所有已解决的问题，发布版本，CI保证 | +| Unmaintained （无维护） | 社区诉求/兴趣驱动 | 合入所有已解决的问题，无版本发布，无CI承诺 | +| End of Life (EOL, 生命周期终止) | 无 | 分支不再接受任何代码 | + +### 分支状态 + +注意：对于`*-dev`分支，vllm-ascend将仅针对 vLLM 某个特定版本创建开发分支，而非全量版本。 因此，您可能看到部分vLLM版本没有对应的开发分支（比如只能看到`0.7.1-dev` / `0.7.3-dev`分支，而没有`0.7.2-dev`分支），这是符合预期的。 + +通常来说，vLLM每个minor版本（比如0.7）均会对应一个vllm-ascend版本分支，并支持其最新的版本（例如我们计划支持0.7.3版本）。如下所示： + +| 分支 | 状态 | 备注 | +|-----------|------------|--------------------------------------| +| main | Maintained | 基于vLLM main分支CI看护 | +| 0.7.1-dev | Maintained | 基于vLLM 0.7.1版本CI看护 | + +## 版本配套 + +vLLM Ascend Plugin (`vllm-ascend`) 的关键配套关系如下: + +| vllm-ascend | vLLM | Python | Stable CANN | PyTorch/torch_npu | +|--------------|---------| --- | --- | --- | +| v0.7.x (TBD) | v0.7.x (TBD) | 3.9 - 3.12 | 8.0.0.beta1 | 2.5.1 / 2.5.1rc1 | + +## 发布节奏 + +### 下一个正式版(`v0.7.x`)发布窗口 + +| 时间 | 事件 | +|------------|-----------------------------------| +| 2025年02月 | RC版本（RC1）, v0.7.1rc1 | +| 2025年03月 | RC版本（RC2）, v0.7.1rc2 or v0.7.3rc1 | +| 2025年03月 | 正式版, 匹配0.7.x最新的vLLM版本: v0.7.1 or v0.7.3 | diff --git a/docs/source/index.md b/docs/source/index.md index eca5ca3..c6fa31f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -50,4 +50,5 @@ features/supported_models :caption: Developer Guide :maxdepth: 1 developer_guide/contributing +developer_guide/versioning_policy ::: \ No newline at end of file