为了帮助我们理解文档中后续各种指南的原因，首先让我们了解一下这个项目典型的补丁系列是如何产生生命周期的。

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

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

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

列表中较早的分支通常是比它们靠前的分支的后代。例如，maint 比 master 是一个“更老”的分支，因为 master 通常在 maint 之上包含提交。

还有“主题”分支，它们包含其他贡献者的工作。主题分支由 Git 维护者（在其 fork 中）创建，以组织邮件列表上当前传入的贡献集，并在定期的“What’s cooking in git.git”公告中列出。要找到主题分支的尖端，请运行 git log --first-parent master..seen 并查找合并提交。此提交的第二个父提交是主题分支的尖端。

选择正确起点的指导原则是：一般来说，始终将你的工作建立在你所做的更改相关的最旧集成分支之上（参见 gitworkflows[7] 中的“向上合并”）。这个原则意味着在绝大多数情况下，新工作的起点应该是 _maint_ 或 _master_ 的最新 HEAD 提交，具体取决于以下情况：

这也意味着，如果你想让你的工作有机会升级到 master，那么 _next_ 或 _seen_ 不适合作为你工作的起点。它们根本不是为作为新工作的基础而设计的；它们只是为了确保正在进行的主题能协同工作。这就是为什么 _next_ 和 _seen_ 经常与邮件列表上的传入补丁重新集成并强制推送以替换它们以前的版本。一个字面上建立在 _next_ 之上的主题，在没有将 _next_ 中的所有其他尚未准备好的主题拖入的情况下，无法合并到 _master_。

例如，如果你正在进行跨整个系统的更改，而其他人也在进行他们自己的跨整个系统的更改，那么你的工作可能会与其他人的工作产生严重的重叠。这种情况可能会诱使你使用 _next_ 作为你的起点（因为它包含了其他人的工作），但这样做意味着你不仅依赖于其他人的工作，还依赖于已经集成到 _next_ 中的来自其他贡献者的所有其他随机事物。并且一旦 _next_ 被新版本更新，你的所有工作都将需要重新定位，以便维护者可以干净地应用它们。

在绝对必须依赖 _next_ 中已存在但 _master_ 中不存在的少数主题分支的真正特殊情况下，你可能想通过 fork _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”。你不必说“目前”——问题陈述中的现状是关于**没有**你更改的代码，按照项目约定。

用命令式语气描述你的更改，例如，“make xyzzy do frotz”而不是“[This patch] makes xyzzy do frotz”或“[I] changed xyzzy to do frotz”，就像你正在给代码库下达命令来改变其行为一样。尽量确保你的解释无需外部资源就能理解。不要提供指向邮件列表存档的 URL，而是总结讨论的相关要点。

你可能想引用历史记录中“更稳定”部分（即在 _maint_、_master_ 和 _next_ 等分支上）的另一个提交，有几个原因：

当你引用一个更稳定分支（如 _master_、_maint_ 和 _next_）上的提交时，请使用“缩写哈希（主题，日期）”格式，如下所示：

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

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

为了改进跟踪谁做了什么，我们要求你通过“签署”你的补丁来认证你编写了该补丁或有权在与我们相同的许可证下分发它。没有签署，我们就无法接受你的补丁。

如果你（并且仅当你）认证以下 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”。

开发者起源证明要求贡献者证明他们知道其贡献的来源，并且他们有权在项目的许可证下提交它。当提交大量由 AI 工具生成的内容时，尚不清楚这是否能在法律上满足要求。

AI 生成内容的另一个问题是，AI 仍然经常会产生幻觉或仅仅产生不好的代码、提交消息、文档或输出，即使你指出了它们的错误。

为了避免这些问题，我们将拒绝任何看起来是 AI 生成的、听起来过于正式或冗长、看起来像 AI 垃圾、表面上看起来不错但没有意义，或者发送者不理解或无法解释的内容。

我们强烈建议谨慎负责地使用 AI 工具。

贡献者通过使用 AI 来指导和帮助他们逐步自行完成解决方案，而不是要求一个他们然后大部分复制粘贴的完整解决方案，从而受益更多。他们还可以使用 AI 来帮助调试，或者检查明显的错误、可以改进的地方、不符合我们的风格、指南或反馈的地方，然后再发送给我们。

基于 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 编码的，则通过管道传输到程序的是您在*Article*缓冲区中解开 MIME 后看到的表示。这通常不是您想要的，原因有两个。它倾向于搞砸非 ASCII 字符（最明显的是人名），以及空格（在补丁中是致命的）。运行“C-u g”以原始形式显示消息，然后再使用“|”来运行管道，可以解决这个问题。