为了帮助我们理解文档后面给出的各种指南背后的原因，首先让我们了解此项目典型补丁系列的生命周期是怎样的。

在以下各节中，列出了许多技术和约定，以帮助你的补丁在此类生命周期中获得有效审查。

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

有几个重要的分支需要注意。即，gitworkflows[7] 中讨论了四个集成（integration）分支

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

还有“主题”分支（topic branches），其中包含其他贡献者的工作。主题分支由 Git 维护者（在其派生仓库中）创建，用于组织邮件列表中当前收到的贡献集，并在定期发布的“git.git 正在进行中”公告中列出。要查找主题分支的尖端（tip），运行 git log --first-parent master..seen 并查找合并提交。此提交的第二个父提交是主题分支的尖端。

选择正确起点有一条指导原则：通常，你的工作应始终基于与你的更改相关的最旧的集成（integration）分支（参见 gitworkflows[7] 中的“向上合并”）。这条原则意味着，绝大多数情况下，新工作的起点应该是 maint 或 master 的最新 HEAD 提交，具体取决于以下情况：

这也意味着，如果你希望你的工作有实际机会晋级到 master，那么 next 或 seen 不适合作为你工作的起点。它们根本不是为了用作新工作的基础而设计的；它们只是为了确保正在进行的主题能够很好地协同工作。这就是为什么 next 和 seen 经常与邮件列表中收到的补丁重新集成，并被强制推送以替换它们自己的先前版本。一个完全建立在 next 之上的主题不能在不将 next 中所有其他主题（其中一些可能尚未准备好）拖入的情况下合并到 master。

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

在真正特殊的情况下，如果你绝对必须依赖 next 中已有但 master 中没有的少数几个主题分支，你可能希望通过派生 master 并将所需的主题分支合并到其中来创建自己的自定义基础分支。然后你可以在这个基础分支之上进行工作。但请记住，这个基础分支只对你私有。因此，当你准备将补丁发送到列表时，请务必在你的附函中说明你是如何创建它的。这一关键信息将允许他人在他们那边重新创建你的基础分支，以便他们尝试你的工作。

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

除非你的补丁确实微不足道，否则你不应该发送工作树和提交头之间生成的补丁。相反，始终创建一个包含完整提交消息的提交，并从你的仓库生成一系列补丁。这是一种良好的规范。

为更改提供足够详细的解释，以便人们可以在不阅读实际补丁文本的情况下判断它是否是件好事，以确定代码是否很好地实现了解释所承诺的功能。

如果你的描述开始变得太长，这表明你可能需要将提交拆分为更细粒度的部分。话虽如此，那些清晰描述有助于审阅者检查补丁和未来维护者理解代码的事项的补丁，是最美观的补丁。在主题中很好地总结要点，并描述更改的动机、更改所采取的方法，以及（如果相关）这与先前版本有何实质性不同的描述，都是值得拥有的好东西。

确保你为正在修复的 bug 编写了测试。请参阅 t/README 获取指导。

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

推送到 https://github.com/git/git 的派生仓库将使用其 CI 集成来在 Linux、Mac 和 Windows 上测试你的更改。有关详细信息，请参阅 GitHub CI 部分。

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

我们目前对拼写和语法采用了美国英语和英国英语规范的自由混合，这多少有些不幸。然而，一个仅仅为了纠正不一致性而触及所有文件的巨大补丁是不受欢迎的。此类补丁可能与其他更改产生潜在冲突，不值得。我们倾向于通过小型且易于理解的补丁，在附近进行其他实际工作的同时（例如，为了清晰度重写一个段落，同时将英式拼写改为美式拼写），逐步地使不一致性与美式英语保持一致。明显的印刷错误修正（“teh” → “the”）更受欢迎，最好作为独立于其他文档更改的补丁提交。

哦，还有一件事。我们对空白字符很挑剔。确保你的更改不会触发 templates/hooks--pre-commit 中随附的示例 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 上：

为了更好地追踪谁做了什么，我们要求你通过“签署”（"signing off"）你的补丁来证明你编写了该补丁，或者有权在与我们相同的许可下传递它。没有签署，我们无法接受你的补丁。

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

你将一个“Signed-off-by”尾行添加到你的提交中，它看起来像这样：

如果你使用 -s 选项运行 git-commit 命令，Git 可以添加此行。

请注意，当你按照上述 D-C-O 规则转发他人的补丁时，你可以放置你自己的 Signed-off-by 尾行。实际上，我们鼓励你这样做。不要忘记在正文开头放置一个“From: ”行，以便将更改正确归因于其真正的作者（参见上面的（2））。

此过程最初来源于 Linux 内核项目，因此我们的规则与他们的非常相似，但签署你的补丁具体意味着什么在不同项目之间有所差异，因此可能与你习惯的项目有所不同。

另请注意，Signed-off-by 尾行中使用了真实姓名。请不要隐藏你的真实姓名。

如果你愿意，可以在末尾添加额外的尾行

虽然如果情况允许，你也可以创建自己的尾行，但我们鼓励你使用上面突出显示的本项目中的常用尾行之一。

只将尾行的第一个字母大写，即优先使用“Signed-off-by”而不是“Signed-Off-By”，以及“Acked-by:”而不是“Acked-By”。

基于 Git 的差异工具生成 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”以原始形式显示消息可以解决这个问题。