为了帮助我们理解稍后文档中给出的各种指南背后的原因，首先让我们了解一下本项目的典型补丁系列的生命周期。

在以下部分，列出了许多技术和约定，以帮助您的补丁在这样的生命周期中得到有效审查。

作为初步步骤，您必须首先为您的工作选择一个起点。通常这意味着选择一个分支，尽管从技术上讲，它实际上是一个特定的提交（通常是分支的 HEAD 或顶端）。

有几个重要的分支需要注意。即，有四个集成分支，如 gitworkflows[7] 中所述

列表中较低的分支通常是其前面分支的后代。例如，maint 是比master“更旧”的分支，因为master 通常在maint之上有补丁（提交）。

还有“主题”分支，其中包含来自其他贡献者的工作。主题分支由 Git 维护者（在其 fork 中）创建，以组织邮件列表中当前传入的贡献集，并在常规的“Git.git 中正在准备什么”公告中逐条列出。要查找主题分支的顶端，请运行git log --first-parent master..seen并查找合并提交。此提交的第二个父级是主题分支的顶端。

选择正确起点有一个指导原则：一般来说，始终以与您的更改相关的最旧的集成分支为基础（请参阅 gitworkflows[7] 中的“向上合并”）。此原则意味着在绝大多数情况下，新工作的起点应基于以下情况，以maint或master的最新 HEAD 提交为基础

这也意味着，如果您希望您的工作有现实的机会晋升到master，则next或seen不适合作为您工作的起点。它们的设计并非用于用作新工作的基础；它们仅仅是为了确保正在进行的主题能够很好地协同工作。这就是为什么next和seen经常与邮件列表中的传入补丁重新集成并强制推送以替换其先前版本的原因。从字面上构建在next之上的主题无法合并到master，而无需拖入next中的所有其他主题，其中一些主题可能尚未准备好。

例如，如果您正在进行全树范围的更改，而其他人也正在进行自己的全树范围的更改，那么您的工作可能与其他人的工作有严重的重叠。这种情况可能会诱惑您使用next作为起点（因为它将包含其他人的工作），但这样做意味着您不仅依赖于其他人的工作，还依赖于已集成到next中的其他贡献者的所有随机内容。并且，一旦next更新为新版本，无论如何都需要重新设置所有工作的基础，以便维护者能够干净地应用它们。

在极少数特殊情况下，如果您绝对必须依赖一些已经在next分支但未在master分支中的主题分支，则可以考虑通过复制master分支并将其所需主题分支合并到其中来创建您自己的自定义基础分支。然后，您可以在此基础分支之上进行工作。但请记住，此基础分支仅为您个人所知。因此，当您准备好将补丁发送到列表时，请务必在您的附信中说明您是如何创建它的。此关键信息将允许其他人根据您的说明在他们自己的环境中重新创建您的基础分支，以便他们尝试您的工作。

最后，请注意，系统某些部分有专门的维护人员，他们拥有自己的独立源代码存储库（请参阅下面的“子系统”部分）。

除非您的补丁非常简单，否则您不应发送在工作树和提交头部之间生成的补丁。相反，始终使用完整的提交消息进行提交，并从您的存储库生成一系列补丁。这是一个良好的习惯。

提供对更改的解释，其详细程度足以让人们判断这是否是件好事，而无需阅读实际的补丁文本以确定代码是否按解释承诺的那样工作。

如果您的描述开始变得太长，则表示您可能需要将提交拆分为更细粒度的部分。话虽如此，清晰描述有助于审查者检查补丁以及未来维护者理解代码的补丁是最漂亮的补丁。能够在主题中很好地概括要点，并描述更改的动机、更改采用的方法，以及如果相关，此更改与先前版本有何重大区别的描述，都是很好的内容。

确保您为要修复的错误编写了测试。有关指导，请参阅t/README。

添加新功能时，请确保您有新的测试来展示该功能在应该触发时触发新的行为，并在不应该触发时不触发。在进行任何代码更改后，请确保整个测试套件都通过。修复错误时，请确保您有新的测试，如果其他人意外地破坏了您修复的内容，这些测试会中断，以避免出现回归。此外，尝试将您的工作合并到next和seen中，并确保测试仍然通过；其他人的主题如果仍在进行中，可能会与您在主题中尝试执行的操作产生意外的交互。

推送到https://github.com/git/git的fork将使用他们的CI集成在Linux、Mac和Windows上测试您的更改。有关详细信息，请参阅GitHub CI部分。

不要忘记更新文档以描述更新后的行为，并确保生成的文档集格式良好（尝试Documentation/doc-diff脚本）。

我们目前在美国和英国英语规范之间采用了自由混合的拼写和语法，这多少有些不幸。但我们不欢迎那些为了纠正这种不一致而修改所有文件的巨大补丁。此类补丁可能导致与其他更改发生冲突，这并不值得。我们更倾向于逐步将不一致之处统一为美国英语，并以小而易于理解的补丁的形式进行，作为在附近进行其他实际工作（例如，为了清晰起见重写一段话，同时将英国英语拼写改为美国英语）的副作用。明显的印刷错误更受欢迎（“teh”→“the”），最好以独立补丁的形式提交，与其他文档更改分开提交。

哦，还有一件事。我们对空格很挑剔。确保您的更改不会触发templates/hooks--pre-commit中提供的示例预提交钩子中的错误。为了帮助确保这种情况不会发生，在提交更改之前，请运行git diff --check。

解释更改的日志消息与更改本身同等重要。您的代码可能写得很清楚，并带有代码内注释以充分解释其如何与周围代码一起工作，但未来需要修复或增强您的代码的人需要知道您的代码为什么这样做，原因有几个。

您的日志消息的目的是传达更改背后的原因，以帮助未来的开发人员。审查人员还将确保您提出的日志消息能够很好地达到此目的。

提交消息的第一行应该是简短的描述（50个字符是软限制，请参阅git-commit[1]中的DISCUSSION），并且应该省略句号。在大多数情况下，在第一行前面加上“area: ”也是惯例，其中area是文件名或要修改的代码一般区域的标识符，例如：

如果您不确定要使用哪个标识符，请在要修改的文件上运行git log --no-merges以查看当前的约定。

“area:”前缀后的标题句子省略句末的句号，并且其第一个单词不应大写（仅对“area:”前缀后的标题中的第一个单词省略大写），除非有理由将其大写，而不是因为它在句子中是第一个单词。例如，“doc: clarify…​”，而不是“doc: Clarify…​”，或者“githooks.txt: improve…​”，而不是“githooks.txt: Improve…​”。但“refs: HEAD is also treated as a ref”是正确的，因为即使HEAD出现在句子的中间，我们也将其全部大写。

正文应提供有意义的提交消息，该消息

描述现状的问题陈述用现在时态编写。写“当给定输入Y时，代码执行X”，而不是“当给定输入X时，代码过去执行Y”。您不必说“目前”——问题陈述中的现状是关于没有您的更改的代码，这是项目的约定。

以祈使语气描述您的更改，例如“使xyzzy执行frotz”，而不是“[此补丁]使xyzzy执行frotz”或“[我]更改了xyzzy以执行frotz”，就好像您正在命令代码库更改其行为一样。尽量确保您的解释可以在没有外部资源的情况下被理解。不要提供邮件列表存档的URL，而是总结讨论的相关要点。

您可能希望在历史记录的“更稳定”部分（即在maint、master和next等分支上）引用另一个提交，原因如下：

当您引用更稳定分支（如master、maint和next）上的提交时，请使用“简写哈希（主题，日期）”格式，如下所示：

gitk的“复制提交引用”命令可用于获取此格式（主题用一对双引号括起来），或者可以使用以下git show调用：

或者，在不支持--pretty=reference的旧版Git上：

为了更好地跟踪谁做了什么，我们请您证明您编写了补丁或有权在与我们的许可证相同的许可证下传递它，方法是“签署”您的补丁。如果没有签署，我们将无法接受您的补丁。

如果（且仅当）您认证以下D-C-O

您需要在提交信息中添加一个“Signed-off-by”的尾部信息，格式如下：

如果您使用 `git-commit` 命令并添加 `-s` 选项，Git 会自动添加此行。

请注意，当您转发他人的补丁并遵循上述 D-C-O 规则时，也可以添加您自己的 `Signed-off-by` 尾部信息。事实上，我们鼓励您这样做。不要忘记在开头添加一行“From: ”来正确地将更改归因于其真正的作者（参见上面的 (2)）。

此流程最初来自 Linux 内核项目，因此我们的规则与他们的规则非常相似，但签署补丁的确切含义因项目而异，因此可能与您习惯的项目有所不同。

还要注意，`Signed-off-by` 尾部信息中使用了真实姓名。请不要隐藏您的真实姓名。

如果您愿意，可以在末尾添加额外的标签

虽然您也可以根据情况创建自己的尾部信息，但我们鼓励您使用本项目中上面突出显示的常用尾部信息之一。

标签的第一个字母大写即可，例如，使用“Signed-off-by”而不是“Signed-Off-By”，使用“Acked-by:”而不是“Acked-By”。

基于 Git 的 diff 工具会生成 unidiff，这是首选格式。

如果您要修改的补丁涉及文件重命名，请不要害怕使用 `git diff` 或 `git format-patch` 的 `-M` 选项。接收端可以很好地处理它们。

请确保您的补丁不会添加已注释掉的调试代码，或包含与补丁试图实现的目标无关的任何额外文件。生成补丁后，请务必检查补丁，以确保准确性。在发送之前，请确保它可以干净地应用于您在“选择起始点”部分中选择的起始点。

在修改对补丁所做的更改时，务必承认与其他正在进行的主题发生冲突的可能性。为了有效地解决这些潜在的冲突，请遵循以下建议的步骤

（Johannes Schindelin）

（Linus Torvalds）

（Daniel Barkalow）

请参阅 git-format-patch[1] 的 MUA-SPECIFIC HINTS 部分。

*Summary* 缓冲区中的“|”可用于将当前消息传递到外部程序，这是一种方便的方式来驱动 git am。但是，如果消息是 MIME 编码的，则传递到程序中的内容是在解包 MIME 后在 *Article* 缓冲区中看到的内容。由于两个原因，这通常不是您想要的。它往往会弄乱非 ASCII 字符（最显着的是人名），以及空格（在补丁中是致命的）。在使用“|”运行管道之前，运行“C-u g”以原始形式显示消息可以解决此问题。