# Endless 贡献准则

欢迎向 Endless 提交测试用例、补丁或新特性 👏！我们欢迎任何形式的贡献。但在你按下 _"New Pull Request"_ 那个绿色按钮之前，请你阅读本贡献指南。
本指南指出了 Endless 代码审阅（code review）的一般流程和注意事项，以及我们对 PR 代码风格和元信息（如标签）的建议。

我们将贡献分为：**测试用例（test case）** 和 **Endless 框架本体的特性和补丁** 两类，分别对应本文的后两节。本文的第一节是 **一般准则**，
所有的贡献（无论类别）均适用一般准则。

## 一般准则

 - Be kind to each other! 😉
 - 编写代码的 commit log 时，尽量遵照 `(<type or module>) <description>` 的格式。 
   如：`(pkg/matcher) introduce TolerateByDuration`、`(testcase/oltp) adapt to the scenario test`、
   `(bugfix) fix toleration.go`。 模块名（`<module>`）是依照代码所属的 Golang 包划分的，
   具体可选项请参照本准则的后两节。
 - 合并代码时，请使用 Squash and Merge。
 - 在使用 Squash and Merge 合并代码前，请清理 commit log，去除其中诸如 "format"、"address comments" 等无意义的部分。
   提交历史应仅包含对该 PR 内容的一般性概述。
 - 我们已经配置了 `CODEOWNERS`，大多数情况下你的贡献会自动请求一位代码所有者前来审阅。
   对于新增加测试用例可能需要额外的步骤，详见下文。
 - 不要请求太多人审阅。如果你实在着急，可以在评论区圈TA并适当地催一下：-）
 - **请尽量提交大小适宜的 PR。** 怎样才算是适宜的大小？这是个困难的问题... 
   对于 Endless 框架本体的特性和补丁，**500 行** 就算比较大了 Endless 是作为测试的基础设施提供的，所以对它的修改需要比较细致的测试和审阅；
   对于测试用例，一般而言即便是只有你懂它也不会有很大问题，所以我们通常只审阅一般的代码风格要求以及测试用例和 Endless 产生交互的部分，故
  **1000 行** 以内的测试用例 PR 都是 ok 的。如果你的测试用例 PR 太长，请抽几个用例到另一个 PR 提交。
   过长的 PR 容易 block 审阅流程，还会导致不必要的 conflict。

_测试用例（test case）_ 型贡献请参阅下一节 _Endless 框架本体的特性和补丁_ 型贡献请参阅下下节。

## 贡献测试用例（test case）

> **与 Endless 框架本体有关的贡献，不适用于本节。**

 - **请详细阅读 [Endless 用例编写风格指南](https://github.com/pingcap/endless/blob/master/docs/style-guide.md)** ，
   在那份文档中我们给出了有关测试用例编写的诸多建议。我们注意到不少对新编写的测试用例的审阅意见其实都是已经在风格指南中列出的内容，
   所以阅读风格指南**十分重要**。另外一点是风格指南经常更新，建议不时查看。
 - 有关 **标签（label）** 的注意事项：
   - 如果你的用例还在编写因此需要推迟代码审阅，**请给它打上醒目的 `do-not-merge/work-in-progress` 标签。** 
     仅仅在标题中注明 "DNM" 或 "WIP" 是不够的，那很容易看错。
   - 如果你的 PR 是对已有用例的 bugfix，请使用 `bug` 标签。
 - **提交新的测试用例时，除了自动请求的代码所有者外，你还需要再请求 *至少一位* 研发同学的审阅。**
 - 如果提交的测试用例是全新的（在 `testcase` 目录中创建了新的目录），你可能会发现默认的代码所有者是*上一级目录*的所有者而不是你。
   这时候，你需要修改 `.github/CODEOWNERS` 文件，将你自己设为新增的子目录的所有者，
   就像 [这个 PR](https://github.com/pingcap/endless/pull/358/files) 所做的那样 。
 - 如上所述，除了这些，*一般准则* 中对于 PR 大小和 review 流程等的一般性建议仍然适用。

## 贡献 Endless 框架本体的特性和补丁

> **与测试用例（test case）有关的贡献，不适用于本节。**

 - 有关 **标签（label）** 的注意事项：
   - 建议给所有 Endless 相关的贡献打上 `type/endless` 标签。
   - 如果你的 PR 还在编写因此需要推迟代码审阅，**请给它打上醒目的 `do-not-merge/work-in-progress` 标签。** 
     仅仅在标题中注明 "DNM" 或 "WIP" 是不够的，那很容易看错。
   - 如果你的 PR 是对 Endless 的 bugfix，请使用 `bug` 标签。
   - 请按照主要相关代码所属的 Golang package 为贡献（PR 或 Issue）打上 `pkg/<module>` 标签。可选项有：
     - `pkg/chaos`
     - `pkg/client`
     - `pkg/datagen`
     - `pkg/matcher`
     - `pkg/util`
     - `pkg/workloadnode`
 - 请包含足够的测试和文档。对于公开（exported）的函数和结构体，使用 Godoc 语法注释其主要功能。
 - 如上所述，除了这些，*一般准则* 中对于 PR 大小和 review 流程等的一般性建议仍然适用。