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

在接下来的章节中，列出了许多技术和惯例，以帮助你的补丁在这样的生命周期中得到有效的评审。

作为准备步骤，你必须首先为你的工作选择一个起点。通常这意味着选择一个分支，尽管从技术上讲，它实际上是一个特定的提交（通常是该分支的 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 中的少数选定主题分支，你可以通过从 master 派生并合并所需的主题分支来创建自己的自定义基准分支。然后你可以在此基准分支之上工作。但请记住，这个基准分支只有你私下知道。因此，当你准备好将补丁发送到列表时，请务必在自述信（cover letter）中说明你是如何创建它的。这一关键信息将允许他人在他们那边重建你的基准分支，以便试用你的工作。

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

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

对更改给出足够详细的解释，以便人们在不阅读实际补丁文本的情况下，就能判断这样做是否是一件好事，并确定代码在多大程度上实现了说明中所承诺的内容。

如果你的描述开始变得太长，这预示着你可能需要将提交拆分为更细粒度的部分。话虽如此，清晰描述有助于评审人员检查补丁、帮助未来维护者理解代码的补丁是最完美的补丁。在标题中很好地总结要点，描述更改的动机、更改所采取的方法，以及（如果相关的话）这与之前版本有何实质性不同，这些都是很好的做法。

确保你为所修复的错误编写了测试。请参阅 t/README 获取指导。

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

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

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

目前我们混合使用了美式英语和英式英语的拼写和语法规范，这有些令人遗憾。但是，不欢迎为了纠正这种不一致而触及各处文件的大型补丁。这种补丁可能与其他更改产生冲突，不值得这样做。我们倾向于在进行其他实际工作的同时（例如，为了清晰起见重写一段话，同时将英式拼写改为美式），通过细小且易于消化的补丁逐步将不一致之处调和为美式英语。显而易见的排版修复更受欢迎（例如 "teh" → "the"），最好作为独立于其他文档更改的补丁提交。

哦，还有一件事。我们对空白字符（whitespaces）非常挑剔。确保你的更改不会触发 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 出现在句子中间，我们也将其拼写为全大写。

正文应提供有意义的提交消息，其中应：

描述现状的问题陈述应使用一般现在时。写成 "The code does X when it is given input Y"（当给定输入 Y 时，代码执行 X），而不是 "The code used to do Y when given input X"（当给定输入 X 时，代码过去执行 Y）。你不需要说 "Currently"（当前）——按照项目惯例，问题陈述中的现状是指没有你的更改时的代码状态。

使用祈使语气描述你的更改，例如 "make xyzzy do frotz"（让 xyzzy 执行 frotz），而不是 "[This patch] makes xyzzy do frotz"（本补丁让 xyzzy 执行 frotz）或 "[I] changed xyzzy to do frotz"（我更改了 xyzzy 以执行 frotz），就好像你在命令代码库改变其行为一样。尽量确保你的解释在没有外部资源的情况下也能被理解。不要只给出邮件列表归档的 URL，而是总结讨论的相关要点。

有几个原因可能会让你想要引用历史记录中“更稳定”部分的另一个提交（即在 maint、master 和 next 等分支上的提交）：

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

可以使用 gitk 的 "Copy commit reference" 命令来获取此格式（主题括在双引号中），或者调用如下 git show 命令：

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

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

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

开发者原创证明 (DCO) 要求贡献者证明他们了解其对项目贡献的来源，并有权在项目许可下提交。目前尚不清楚，在提交由 AI 工具生成的大量内容时，是否能从法律上满足这一要求。

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 编码的，传输到程序中的内容是你展开 MIME 后在 *Article* 缓冲区中看到的表示形式。出于两个原因，这通常不是你想要的：它往往会搞砸非 ASCII 字符（最明显的是人名中的字符），以及空白字符（对补丁来说是致命的）。在执行 "|" 运行管道之前运行 "C-u g" 以原始形式显示消息可以解决此问题。