贡献代码

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" 工作流程。

  1. 将 GitHub 上的 Milvus 公有库 Fork 至自己的账户中;
  2. 在私有库中新建分支,并在其中 提交更改
  3. 提交 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 时参考并遵守以下风格指南:

最佳实践

以下,我们列出了一些向 Milvus 贡献代码时可以用到的技巧:

  • 将一个大的改动分成一系列的小改动,每个小改动都是一个易于理解的部分。

  • 合并所有 commit,帮助我们维持清晰的 Git 历史记录。

  • 保持 commit message 简明扼要。

  • 不要在提交消息中包含 @someonefixes #<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_testmilvus/tests20/python_client 目录下。 运行集成测试:

pytest --tags=smoke .
  • 端对端测试:完整的功能测试用例。 这些测试是用 Python 编写的,存储在 milvus/tests/python_testmilvus/tests20/python_client 目录下。 运行端对端测试:
pytest .

持续集成(Continuous integration,即 CI)将在 PR 上运行单元测试和集成测试,其结果将在 GitHub Pull Request 状态中更新。 任何测试失败都会阻止代码合并。

© Milvus 2021Milvus, and associated open source project names are trademarks of the LF AI & Data Foundation