提交信息&PR 规范

本文档描述了应用于 MatrixOrigin 的所有存储库的提交消息 (commit mesage) 和 PR(pull request) 的样式规范。当你提交代码时,务必遵循这种规范,保证提交的质量。

一条好的 commit message 有多重要?

  • 加速审阅流程
    • 帮助审阅者更好地理解 PR 内容
    • 可以忽略不重要的信息
  • 有助于撰写发布公告
  • 帮助其他人了解前因后果

什么是好的 commit message?

我们认为有以下要素:

  1. What is your change? (必要)

    它可能修复了一个特定的 bug,添加了一个 feature,提高了性能、可靠性或稳定性,或者只是保障安全性而进行的更改。

  2. Why this change was made? (必要)

    对于简要的补丁,这部分可以省略。

  3. What effect does the commit have? (可选)

    除了必然会产生的影响之外,可能还包括基准测试性能变化、对安全性的影响等。对于简要的改动,这部分可以省略。

如何写好一条 commit message

要写出一条优质的 commit message,我们建议您遵循规定的格式,培养良好的习惯并使用规范的语言。

规定的格式

请在提交时遵循以下格式:

  1. <subsystem>: <what changed>
  2. <BLANK LINE>
  3. <why this change was made>
  4. <BLANK LINE>
  5. <footer>(optional)
  • 第一行

    • 不超过 70 个字符
    • 如果该改动影响了两个模块,请使用逗号和(带空格)进行分隔,如 util/codec, util/types:
    • 如果该改动影响了三个及以上的模块,请使用 *,如 *:
    • 在冒号后的文本中使用小写字母。例如:”media: update the DM architecture image”
    • 不要在最后添加句号。
  • 第二行请留白

  • 第三行 “why” 部分,如果没有特定的原因,您可以使用以下表述,如 “Improve performance”,”Improve test coverage.”

  • 其他行不超过 80 个字符。

良好的习惯

  • 进行总结
  • 清楚地描述该方案的逻辑,避免 misc fixes 等表达
  • 叙述当前方案的限制
  • 不要以句号结尾
  • 注意代码的证明和测试
  • 交代前因后果

规范的语言

  • 在第一行使用祈使句
  • 使用简单的动词 (如 “add” not “added”)
  • 保证标准无误的语法
  • 前后使用的单词、短语保持一致
  • 使用短句
  • 不要使用过长的复合词
  • 非必要不缩写

Pull Request 规范

关于 Pull Request 中的描述,请参考下面的 Pull Request 模板,涵盖必要信息:

  1. **What type of PR is this?**
  2. - [ ] API-change
  3. - [ ] BUG
  4. - [ ] Improvement
  5. - [ ] Documentation
  6. - [ ] Feature
  7. - [ ] Test and CI
  8. - [ ] Code Refactoring
  9. **Which issue(s) this PR fixes:**
  10. issue #
  11. **What this PR does / why we need it:**
  12. **Special notes for your reviewer:**
  13. **Additional documentation (e.g. design docs, usage docs, and so on.):**

如果需要,您也可以使用清单来列举内容,Markdown 语法如下:

  1. - [x] A checked line, something already done or fulfilled
  2. - [ ] An unchecked line, something not finished yet

对于非常简要的 Pull Requests,你可以省略上面的一些信息。 非常感谢您的贡献!