如何成为补丁大师？¶

当您在实现一项新功能或向现有功能添加文档时，很容易被这些任务本身所牵扯住，而忽略了构建变更的一些不成文规则。

本节将指导您了解如何创建人们想查看的补丁。

允许您:

知道如何构建补丁，以便在整个审核过程中更容易维护
知道如何构建补丁，易于社区成员查看

合适的大小¶

审核大型补丁非常不方便且耗时，因此我们始终建议您将变更分解为较小的补丁。

虽然没有一个神奇的数字规范**使变更量的大小保持尽可能小**，但最好总变更量要少于几百行。少量代码变更但是进行大量测试的补丁与大量代码变更所需的工作量相同。

在极少数情况下，当没有很好的逻辑分解依据时，您的补丁可能会增长到一千行或更多。在某些情况下，这是可以接受的，例如因为您无法将相关的测试变更提取到另一个补丁中，但不建议这样做。

始终尝试将尽可能多的变更提取到单独的补丁中，例如文档或功能实现中不依赖于底层通用功能的逻辑部分。

补丁越长，需要花费审核的时间越多；尽可能保持长度合理。在无法做到的地方，您可以通过添加代码注释并编写详细的提交消息来描述您在补丁中引入的变更，从而帮助审阅者。

补丁链，Depends-On标签和Gerrit标题¶

对于复杂的功能实现工作，当您需要对同一项目或多个项目的多个模块进行更改时，在管理依赖项时需要格外小心。

根据设计的结构，有多种选择。您可以在补丁链中组织你的更改，也可以使用’Depends-On’标签。

Depends-On标签¶

当您在多个项目仓库中进行更改时，可以使用’Depends-On’标签标记相关依赖的补丁。该标记将作为链接显示在提交消息中，该链接可以帮助您以及审阅者在更改的依赖关系之间进行跟踪和导览。

‘Depends-On’标签是您所做更改的标记，当使用标签时，除非提交更改的所有依赖项均已获得，否则补丁将无法合并。

该标签也可以应用于为同一项目仓库建议的补丁。在这种情况下，更改是可以彼此分隔，独立维护的。这意味着，如果您需要修复评论注释中的更改，则可以在每个补丁的基础上进行更改。对于为每个补丁重新设置基准代码也是同样适用。

备注

如果您使用’Depends-On’标签，则需要下载为功能实现或者文档更改所做的所有更改，以测试集成了这些更改后的功能或构建集成了这些更改后的文档。在这种情况下，Git将不会自动处理依赖项。

补丁链¶

在某些情况下，当您将所需更改分解为较小的补丁时，它们之间将不可避免地具有直接依赖性，从而使得您无法进行独立更改。您需要将更改组织成一个链来维护依赖关系，当您使用这些更改时，需要格外小心。

即使有一组补丁链，您仍需要将代码更改和相关测试保留在一个补丁中，因为您不能保证两个部分都能及时整合进一次发布中。

当有一组补丁链后，Gerrit可以通过在Gerrit UI右上角的“相关联变更（Related Changes）”中列出所有提交标题来帮助您。标题也是链接，可帮助您在更改之间导览，以在上载新版本时查看它们。

如何处理补丁链¶

如果您牢记下面一些建议，则修补链很容易处理：

始终为这些更改建立一个本地分支（local branch），以确保您不会将其与其他功能或错误修复相关的更改混在一起。
始终通过重新调整整个补丁链为基础，将补丁链作为一个更改整体来处理，并在修改补丁以修复评论注释或向补丁添加更改时保持最新。
要修改补丁链中的补丁，您将需要使用交互式复位基础（rebase）：

git rebase -i HEAD^

从补丁链顶部开始，您将需要与要编辑的补丁数量一样多的’^’。另外，您可能希望使用 git-restack ，这会为您找出合适的 git rebase 命令。

Gerrit还为您提供了编辑补丁本身或仅提交消息的选项，还有更多选项可用于更高级的更改，例如修改作者。

要下载完整的补丁链，您需要下载顶层补丁，Git会自动下载补丁链中的所有相关补丁。
如果只需要修改补丁链中的顶层补丁，可以用更新单个补丁的方式来完成。
当您上传补丁链中的更改时，只会上传被更新的补丁。这也意味着补丁链中较低层的补丁的评论得分数将保持不变。
始终检查对每个补丁所做的更改，并注意将正确的更改应用到正确的位置，因为补丁仍会单独合并，并且不能保证整个补丁链都可以同时合并进去。

有关管理补丁链的更深入的信息，请参见教程：开发一系列变更。

Gerrit标题¶

当您上传更改以进行审核时，可以选择为更改指定标题。尽管Gerrit标题不会对补丁增加依赖性，但是您可以基于标题进行搜索，该搜索将向您显示所有具有相同标题的补丁的所有相关更改。 Gerrit还将在评论页面右上角的“相同标题（Same Topic）”列中向您显示这些标题。

这是帮助跟踪相关更改的好方法，可以将其用作功能实现，错误修复或文档工作。

如何组织您的更改？¶

当您的工作项增长到特定大小以上并且您需要上传多个补丁时，至关重要的是，在补丁链或是独立更改的情况下，合理地组织它。

一个优良作法是按项目中的模块将更改分组，在OpenStack Compute服务中有例如virt driver相关的改变，compute manager相关的改变和api相关的改变

通过将每个模块的更改分组，您还可以按照组件的层次结构来构建补丁链或依赖关系，并始终保持API更改的最新状态，因为这将启用新功能，并且更改将取决于您需要进行设计的所有其他方面。

除此之外，您还可以研究该功能以找到更小的构件，并使更改量更小。例如，可以先实现对对象的更改，然后在实现新的API功能时使用它。

Structural split of Changes¶

The cardinal rule for creating good commits is to ensure there is only one “logical change” per commit. There are many reasons why this is an important rule:

The smaller the amount of code being changed, the quicker and easier it is to review and identify potential flaws.
If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit.
When troubleshooting problems using Git’s bisect capability, small well defined changes will aid in isolating exactly where the code problem was introduced.
When browsing history using git annotate or git blame, small well defined changes also aid in isolating exactly where and why a piece of code came from.

合适的内容¶

通常来讲，可以上传与任何功能实现或错误报告无关的更改，但审核者不欢迎这些更改。

改进代码或文档应该是更广范围工作的一部分，例如，如果您想修正文档中的错别字，则应该在较大范围的代码块框架下进行改进，比如修正整份指南。同时最好报告一个背景描述包含类似这样的工作项的任务，以便稍后进行跟踪。

代码改进也是类似的。由于社区很大且遍布全球，所以我们有编码准则，但是每个人的风格仍然可以有很大不同。我们不强制执行特定的编码样式，因此请尽量避免不那么受欢迎的修订相关的更改的编码方式，以及应避免使用一些自以为是的参数定义方法。

在进行代码重构的情况下，通过重构方法和删除未使用的代码段使代码更易读且更易于维护，强烈建议您与项目团队协商，并先在StoryBoard中报告一个背景，然后将相关更改上传到Gerrit，以便评论。

如何成为补丁大师？