贡献代码到 DVC

我们欢迎社区对 DVC 的贡献。如果你想修复或更新文档或本网站，请参阅 文档贡献指南。

如何报告问题

在创建新问题（问题反馈或改进请求）之前，请先搜索 问题跟踪器。欢迎提交与项目相关的问题。

对于 dvc.org 网站的问题，请使用这个 GitHub 仓库。

如果你认为可以自行修复或实现某个功能，请阅读下面几段内容，了解如何提交你的更改。

提交更改

• 在 问题跟踪器 中创建一个新问题。
• 如果需要运行测试或用修改后的代码运行 DVC，请先配置好 开发环境。
• Fork DVC 并准备必要的修改。
• 为你的更改在 tests/ 目录中 添加测试。如果你的修改难以编写测试，可以跳过此步骤。没有测试的更改我们也会考虑。
• 运行测试，并确保所有测试都通过。
• 提交一个拉取请求（pull request），并在其中引用所解决的问题。

我们会尽快审核你的拉取请求。感谢你的贡献！

开发环境

获取最新的开发版本。Fork 并克隆仓库：

$ git clone git@github.com:<your-username>/dvc.git

确保已安装 Python 3.8 或更高版本。在 macOS 上，我们建议使用 brew 安装 Python。在 Windows 上，我们建议使用官方的 python.org 发行版。

使用 pip install -e ".[dev]" 以可编辑模式安装 DVC。但在执行此操作之前，我们强烈建议创建一个 虚拟环境：

$ cd dvc
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install --upgrade pip wheel
$ pip install -e ".[dev]"

使用以下命令安装代码风格预提交钩子：

$ pip install pre-commit
$ pre-commit install

就这样。你现在应该可以开始修改代码、运行测试和提交更改了！如果遇到任何问题，请随时在我们的 聊天室 中联系我们。

调试

DVC 命令行接口包含一些默认隐藏在 --help 中的调试工具，但如果同时指定 --verbose 参数，这些工具将显示出来。有关这些调试选项的更多信息，请参见 DVC 调试 Wiki。

编写测试

我们在 tests/unit/ 中有单元测试，在 tests/func/ 中有功能测试。建议编写前者以确保复杂函数和类的行为符合预期。

对于特定功能，你需要结合 pytest 固件（fixtures）使用功能测试，以创建临时目录、Git 和/或 DVC 仓库，并初始化一些文件。一些使用示例请参见 dir_helpers 模块 的文档字符串。

运行测试

运行测试的最简单方式：

$ cd dvc
$ python -m tests

这会使用 pytest 运行完整的测试套件并报告结果。最后你应该会看到类似如下的输出：

$ python -m tests

...

============= 434 passed, 6 skipped, 8 warnings in 131.43 seconds ==============

否则，对于每个失败的测试，你应该会看到以下输出，以帮助你定位问题：

...
[gw2] [ 84%] FAILED tests/unit/test_progress.py::TestProgressAware::test
tests/unit/test_prompt.py::TestConfirm::test_eof
tests/test_updater.py::TestUpdater::test
...
=================================== FAILURES ===================================
____________________________ TestProgressAware.test ____________________________
...
======== 1 failed, 433 passed, 6 skipped, 8 warnings in 137.49 seconds =========

你可以向脚本传递任意额外参数，这些参数将覆盖默认的 pytest 范围：

运行单个测试用例：

$ python -m tests tests/func/test_metrics.py::TestCachedMetrics

运行单个测试函数：

$ python -m tests tests/unit/utils/test_fs.py::test_get_inode

传递额外参数：

$ python -m tests --pdb

代码风格指南（Python）

我们遵循 PEP8 规范，并使用 black 检查代码格式。

对于 文档字符串（docstrings），我们尽量遵循 Google Python 风格指南。

提交消息格式指南

格式：

(component): (short description)

(long description)

Fixes #(GitHub issue id).

消息类型：

• 组件：如适用，列出受影响的一个或多个组件，以逗号分隔
• 简要描述：对补丁的简短说明
• 详细描述：如有需要，更详细的补丁说明
• GitHub issue ID：此补丁所解决的 GitHub issue 的编号

示例：

remote: add support for Amazon S3

Fixes #123