跳到内容

为 Speculators 做出贡献

感谢您考虑为 Speculators 做出贡献！我们欢迎社区的贡献，以帮助改进和发展本项目。本文档概述了贡献的流程和指南。

如何贡献？

为 Speculators 做出贡献的方式有很多

  • 报告 Bug：如果您遇到 Bug，请通过创建 Issue 来告知我们。
  • 建议功能：对新功能有什么想法？创建一个 Issue 来讨论它。
  • 改进文档：通过提交 Pull Request 来帮助我们改进文档。
  • 编写代码：贡献代码来修复 Bug、添加功能或提高性能。
  • 审查 Pull Requests：为开放的 Pull Requests 提供反馈，以帮助维护代码质量。

入门指南

先决条件

在贡献之前，请确保您已安装以下软件

  • Python 3.10 或更高版本
  • pip（Python 包管理器）
  • Tox
  • Git

设置仓库

您可以直接克隆仓库，或者如果您计划将更改贡献回项目，则 Fork 该仓库。

选项 1：克隆仓库

  1. 将仓库克隆到您的本地机器
git clone https://github.com/vllm-project/speculators.git
cd speculators

选项 2： Fork 仓库

  1. 通过点击仓库 GitHub 页面的“Fork”按钮来 Fork 该仓库。

  2. 将您 Fork 的仓库克隆到您的本地机器

git clone https://github.com/<your-username>/speculators.git
cd speculators

安装依赖

要安装该包及开发所需的依赖，请运行

pip install -e .[dev]

-e 标志以可编辑模式安装包，这允许您在不重新安装的情况下更改代码。[dev] 部分安装了开发所需的额外依赖，例如测试和 linting 工具。

注意：Speculators 的数据生成组件（即 src/speculators/data_generation）需要安装 vLLM。此模块中的代码应在单独的环境中运行，并安装 vllm。可以通过安装 datagen 额外项来实现，使用 pip install -e .[datagen]（或开发时使用 pip install -e .[datagen,dev]）。

代码风格和指南

我们遵循严格的代码标准，以确保代码质量和可维护性。请遵守以下指南

  • 代码风格：使用 Ruff 进行格式化和 linting。
  • 类型检查：使用 Mypy 进行类型检查。
  • 测试：为新功能和 Bug 修复编写单元测试。使用 pytest 进行测试。
  • 文档：为代码库的任何更改更新文档。

我们使用 Tox 来简化在隔离环境中运行各种任务。Tox 标准化环境，以确保本地开发、CI/CD 管道和发布之间的一致性。这保证了代码在何处执行都能保持相同的行为。

此外，为了确保代码库的一致性和质量，我们使用 ruff 进行 linting 和风格检查，mypy 进行类型检查，以及 mdformat 对 Markdown 文件进行格式化。

代码质量和风格

要检查代码质量，包括 linting 和格式化

tox -e quality

要自动修复样式问题，请使用

tox -e style

类型检查

要使用 Mypy 确保类型安全

tox -e types

使用 Pre-Commit Hooks 自动化质量检查（可选）

我们使用 pre-commit 在提交前自动化质量检查。Pre-commit hooks 会运行 linting、格式化和类型检查等检查，确保只提交高质量的代码。

要安装 pre-commit hooks，请运行

pre-commit install

这将设置 hooks，使其在每次提交前自动运行。要手动对所有文件运行 hooks，请使用

pre-commit run --all-files

运行测试

对于测试，我们使用 pytest 作为我们的测试框架。我们有针对单元测试、集成测试、端到端测试和数据生成测试的不同测试套件。要运行测试，您可以使用 Tox，它将自动为每个测试套件创建隔离环境。Tox 还可以确保测试在一致的环境中运行，无论在哪里执行。

运行所有测试

运行所有测试

tox

运行特定测试

tox 将为您运行的每个测试设置测试环境。

  • 单元测试（专注于带模拟的单个组件）
tox -e test-unit
  • 集成测试（专注于组件之间的交互，最好不带模拟）
tox -e test-integration
  • 端到端测试（专注于整个系统和用户界面）
tox -e test-e2e
  • 数据生成测试（专注于数据生成过程）

注意：这将创建一个安装了 datagen 额外项（包括 vllm）的环境，并在该环境中执行测试。

tox -e test-datagen

运行带覆盖率的测试

为确保您的更改包含在测试中，请运行

tox -e test-unit -- --cov=speculators --cov-report=html

审查覆盖率报告，以确认您的新代码已得到充分测试。

DCO 签发

我们要求所有提交都进行 DCO 签发。有关更多信息，请参阅 DCO Signoff 文档。

# Sign off a commit as you're making it
git commit --signoff -m"my commit"

# Add a signoff to the last commit you made
git commit --amend --signoff

# Rebase your branch against master and sign off every commit in your branch
git rebase --signoff master

提交更改

  1. 创建分支：为您的更改创建一个新分支
git checkout -b feature/your-feature-name

  1. 进行更改：在适当的文件中实现您的更改。使用清晰且描述性的提交消息提交您的更改。

  2. 更新文档：更新或添加文档以反映您的更改。这包括更新 README 文件、docstrings 和任何相关的指南。

  3. 运行测试和质量检查：在提交更改之前，请确保所有测试通过且代码质量检查已满足

tox
  1. 推送更改：将您的分支推送到您 Fork 的仓库（如果您 Fork 了）
git push origin feature/your-feature-name
  1. 打开 Pull Request：从 Fork 的仓库中，使用“贡献”按钮向原始仓库的主分支打开一个 Pull Request。提供您更改的清晰描述，并链接任何相关的 Issue。

报告问题

如果您遇到 Bug 或有功能请求，请在 GitHub 上创建一个 Issue。请包含尽可能多的详细信息，例如

  • 重现问题的步骤
  • 预期行为和实际行为
  • 环境详细信息（操作系统、Python 版本等）

社区标准

我们致力于营造一个欢迎和包容的社区。请阅读并遵守我们的 行为准则。

其他资源

许可证

通过为 Speculators 做出贡献，您同意您的贡献将根据 Apache License 2.0 进行许可。