贡献代码
Milvus 是一个开源项目,我们欢迎每一位贡献者,也希望所有贡献者都遵守我们的 行为准则。
本篇文档详细说明了开发工作流程中的惯例、提交消息格式、最佳实践以及在向 Milvus 贡献代码时可能需要的其他资源。 如果在参与 Milvus 贡献时遇到任何问题,欢迎 提交 GitHub Issue 或通过 Slack 联系我们的工程师团队。
开始之前
关于搭建开发环境,参见 Milvus Development Guide。
工作目录以及文件介绍
/build:存放在容器内编译 Milvus 并运行 E2E 测试的文件。 /cmd:存放 Milvus 服务的入口模块和一些实用工具。 /configs:存放 Milvus 所需要的配置文件。 /deployments:存放部署 Milvus 清单文件。 /docs:存放 Milvus 的设计文档,开发者指引以及监控文档。 /internal:存放 Milvus 源码,包括 Golang 和 CPP 的所有代码。 /scripts:存放用来编译、安装、代码检查、测试的实用脚本。 /tests:存放 Milvus 的 E2E,smoke 测试文件。 CONTRIBUTING.md:Milvus 代码贡献指南。 DEVELOPMENT.md:从源码编译 Milvus 指南。 Makefile:使用 /scripts 目录里脚本的入口,用以编译、测试、以及代码检查。 LICENSE:Milvus 项目的许可证。
GitHub 工作流程
一般情况下,我们遵循 "fork-and-pull" 工作流程。
- 将 GitHub 上的 Milvus 公有库 Fork 至自己的账户中;
- 在私有库中新建分支,并在其中 提交更改;
- 提交 pull request(PR),等待审阅以及合并。
在向上游提交建议的更改之前,同步 你的私有 Milvus 库。
更多指引,参考 成为 Milvus 贡献者。
prow 机器人
为了管理 GitHub PR 标准流程,Milvus 项目集成了一个 prow 机器人(基于 Kubernetes 的 CI/CD 系统)。它会自动为你的 PR 添加标签并分配审阅者。 你还可以在注释中使用命令行来管理该过程。 详细信息见 命令参考。
PR 常见疑难解答
以下是在 PR 中可能遇到的常见问题以及相应的解决方案:
-
DCO 检查失败:请参阅 DCO 页面 以解决问题。
-
测试用例失败:调整代码以通过测试用例。如果测试用例与你引入的代码更改无关,则通过 re-run jobs 以解决问题。
代码审查
PR 开启后,将会有审阅者对你的代码进行全面检查,检查内容涵盖思路正确性、bug、改进可能性、文档和注释,以及代码风格等方面。
如果你的 PR 长时间未得到回应,你可以在 Slack 的 #pr-reviews 频道中联系相关 reviwer。
风格参考
保持代码、注释、commit message 和 PR 描述的风格一致可以大大加快你的 PR 审查流程。我们强烈建议你在开启 PR 时参考并遵守以下风格指南:
-
代码风格:参考 Effictive Go Style Guide
-
Commit message 和 PR 描述的风格: 参考 good commit messages
最佳实践
以下,我们列出了一些向 Milvus 贡献代码时可以用到的技巧:
-
将一个大的改动分成一系列的小改动,每个小改动都是一个易于理解的部分。
-
合并所有 commit,帮助我们维持清晰的 Git 历史记录。
-
保持 commit message 简明扼要。
-
不要在提交消息中包含
@someone
或fixes #<issue-number>
等关键词。 应当在 PR 描述中说明它们。 -
编写清晰详细的 PR 描述,解释代码更改的原因,并确保有足够的信息供审阅者了解你的 PR。
-
如果你的 PR 完全修复了某个问题,请在 PR 正文中填写
fix #<issue-number>
关键词。 这将在 PR 合并时自动关闭你提到的问题。 -
在 PR 页面中机器人的引导下,为你的 PR 分配合适的审阅者。
测试
贡献者有责任确保提交的代码更改通过测试。 如果遇到问题,在评论中联系 @milvus-io/sig-testing 寻求帮助。
贡献给 Milvus 的代码需要通过多种测试,每个测试都有不同的目标:
-
单元测试:用以验证功能是否按预期运行。 Golang 包含通过 testing package 进行单元测试的内置功能。 每个 PR 必须通过所有单元测试才能合并。 每个单元测试代码都和对应的 Golang 文件一起存放,例如:milvus/internal/allocator/global_id.go 中的功能会在milvus/internal/allocator/global_id_test.go 中进行测试。
-
集成测试:端对端测试的一个子集,用以确保 PR 可以高效合并。 这些测试是用 Python 编写的,存储在 milvus/tests/python_test 和 milvus/tests20/python_client 目录下。 运行集成测试:
pytest --tags=smoke .
- 端对端测试:完整的功能测试用例。 这些测试是用 Python 编写的,存储在 milvus/tests/python_test 和 milvus/tests20/python_client 目录下。 运行端对端测试:
pytest .
持续集成(Continuous integration,即 CI)将在 PR 上运行单元测试和集成测试,其结果将在 GitHub Pull Request 状态中更新。 任何测试失败都会阻止代码合并。