【Deis文档】贡献之PR 清单


注:本文翻译自Deis官方文档,无任何商业目的,转载请注明出处。

用户可以通过GitHub pull requests 的形式向Deis提交变更。

请确保你的 PR 遵循以下清单:
  1. 单个问题
  2. 包含测试
  3. 包含文档
  4. 代码标准
  5. 提交方式


单个问题

当修复或者实现某个GitHub issue 的时候,一定要注意千万不要重构该issue相关的代码,并且也不要修复除该issue以外的其它可能你注意到的bug。如果需要重构或者修复其它bug,你需要创建一个新的 pull request

当一个 PR 不是专注解决某一个问题的时候,就很难确定它的利弊。保证独立的关注点可以让 pull requests 被更快的测试、审查和合并。

pull request中的提交会被git转换成逻辑工作单元,提交中会包括测试已经文档变更详情,所以回退也非常容易。

大部分的 pull requests 都会与一个 GitHub issue 相关联,在 PR 描述(不是commit)中会包含一行如“Closes #1234。” 当你的 PR 被合并的时候,issue 将被关闭。

包含测试

如果你变更或添加功能到任何 Deis 代码,你的变更应该包含必需的测试来证明它是能正常工作的。单元测试可以使用组件实现的语言编写(通常是 Go 或 Python),并且功能和集成测试是使用 Go 编写。测试代码可以在 Deis 项目的 tests/ 目录发现。

当工作期间在当地修改代码的时候,请一直运行测试。确保在提交一个PR之前,你提的变更在你的工作环境通过了 ./tests/bin/test-integration 的所有测试。

查看测试 Deis 获取更多信息。

包含文档

对 Deis 的任何变更都可能影响一个用户的体验,所以一个变更或者额外的功能都需要有相关的文档。Deis 根据docs/ 目录下的文本生成 HTML 的文档,托管在 http://docs.deis.io/

在代码中查看 docs/README.md 获取更多信息。

代码标准

Deis 是一个 GoPython 的项目。对于这两门语言,我们同意 The Zen of Python,其强调简单和可读性。

Go 代码应该一直通过在默认设置上的 gofmt 运行,每行代码最多 99 字符的长度。所有的共有方法都应该有注释并且测试过,使用第三方的 go 包应该最小化,但当这样做,在 Deis 包中的 vendor 代码要需要 godep 工具。

Python 代码应该一直坚持 PEP8,Python 代码风格指南,某行代码超过 99 字符抛出一个 exception。公有方法应该有注释和测试,尽管Deis 使用的 flake8 工具不强迫要求这样做。

设计提议

当考虑一个设计提议的时候,我们寻找的是:
  • 该设计提议解决的问题的描述。
  • 一个修改文档的 pull request,描述你提交的特性。
  • 用提议(在标题) Prefix 你的 pull request。
  • 在报告一个新的之前,请 review 已经存在的提议。


提交方式

git commit 消息必须遵循以下格式:

{type}({scope}): {subject}
<BLANK LINE>
{body}
<BLANK LINE>
{footer}

例如:
feat(logger): add frobnitz pipeline spout discovery

Introduces a FPSD component compatible with the industry standard for
spout discovery.

BREAKING CHANGE: Fixing the buffer overflow in the master subroutine
required losing compatibility with the UVEX-9. Any UVEX-9 or
umVEX-8 series artifacts will need to be updated to umVX format
with the consortium or vendor toolset.


标题行

一个提交消息的第一行是它的标题。它包含了这个变更的主要描述,不超过 50 字符。

{types} 被允许是:
  • feat -> feature
  • fix -> bug fix
  • docs -> documentation
  • style -> formatting
  • ref -> refactoring code
  • test -> adding missing tests
  • chore -> maintenance


{scope} 指定了变更的位置,比如“controller”,“Dockerfiles”,或者是 “.gitignore”。{subject} 应该使用命令的,现在式时态:“change”,不是“changes”或“changed”,不要大写这个动词,或在标题行的最后加一个句号。

消息体

单独的消息体与标题直接有一行空行。body 每行最多 72 个字符。它包含该变更的动机,指出了与先前行为的不同。body 和 footer 应该以完整句的形式写。

消息页脚

单独的页脚与消息体直接有一行空行。提及任何认为有理和迁移注意事项的重大变更。如果变更不能被 Deis 的测试脚本测试,包含指定的用于手工测试的操作指南。

合并的批准

Deis 维护者添加“LGTM”(Looks Good To Me)或者一个相当的评论来指出一个 PR 是可接受的。任何代码变更 - 不仅是一个简单的类型 fix 或一行文档变更 - 要求至少两个维护者接受它。

如果 PR 来自于一个 Deis 维护者,这时他或她应该是关闭者之一。这可以保持 commit 流整洁以及给维护者在是否决定合并这个变更之前重新访问 PR 的权益。

0 个评论

要回复文章请先登录注册