English ▾ 主题 ▾ 最新版本 ▾ SubmittingPatches 最后更新于 2.48.0

此信息特定于 Git 项目

请注意,如果您计划为 Git 项目本身做出贡献,此信息才与您相关。 对于普通的 Git 用户,这绝不是必读的内容。

准则

以下是一些为该项目做出贡献的准则。 还有一个循序渐进的教程,其中涵盖了许多相同的准则。

补丁序列的典型生命周期

为了帮助我们理解本文档后面给出的各种准则背后的原因,首先让我们了解一下该项目的典型补丁序列的生命周期。

  1. 您产生了一个痛点。您编写代码来解决它。您不需要项目的任何预先授权即可这样做。

    您的补丁将由邮件列表中的其他贡献者进行审查,审查将评估各种事项的优点,例如您的补丁背后的总体思路(包括“它首先是否解决了值得解决的问题?”),解决方案设计背后的原因以及实际的实现。 此处给出的准则旨在通过使您的补丁更容易被审阅者理解来帮助您的补丁。

  2. 您将补丁发送到列表并抄送可能需要了解更改的人。您的目标一定是说服他人您正在构建的内容是好的。 您的目标是获得帮助,从而为“痛点”提出比您独自构建的更好的解决方案。

    可能需要知道的人是那些从事您正在修改的代码的人。这些人恰好是最有可能足够知识渊博来帮助您的人,但是他们没有义务帮助您(即,您要求他们提供帮助,而不是要求)。 git log -p -- $area_you_are_modifying 将帮助您找出他们是谁。

  3. 您会收到有关改进的意见和建议。您甚至可能会以“在您的更改之上”的补丁形式获得它们。您应该在准备更新的补丁集时通过邮件列表中的“全部回复”来响应它们,同时考虑到它们。

  4. 润色,改进并将您的补丁重新发送到列表以及花费时间改进您的补丁的人员。 返回步骤(2)。

  5. 当上述迭代改进您的补丁时,维护者可能会从列表中选取这些补丁并将其排队到 seen 分支,以便人们可以更轻松地使用它,而不必自己选取补丁并将其应用到其树中。 在 seen 中没有其他含义。 具体来说,这并不意味着该补丁以任何方式被“接受”。

  6. 当讨论达成共识,即最新迭代的补丁的形状足够好时,维护者会将该主题包括在每周几次发送到邮件列表的“正在烹饪”报告中,并标记为“将合并到next。” 此决定主要由维护者在参与审查讨论的人员的帮助下做出。

  7. 将补丁合并到 next 分支后,讨论仍然可以继续,以通过在顶部添加更多补丁来进一步改进它们,但是当一个主题合并到 next 时,希望每个人都同意该主题的范围和基本方向是合适的,因此,此类增量更新仅限于小的更正和润色。 一个主题在 next 中经过一段时间(例如 7 个日历日)的烹饪而无需进一步的调整后,它将合并到 master 分支并等待成为下一个主要版本的一部分。

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

选择一个起点。

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

有几个重要的分支需要注意。 即,正如 gitworkflows[7] 中所讨论的,有四个集成分支

  • maint

  • master

  • next

  • seen

列表中的较低分支通常是位于其之前的分支的后代。 例如,maint 是比 master “更旧”的分支,因为 master 通常在 maint 之上有补丁(提交)。

还有一些“主题”分支,其中包含来自其他贡献者的工作。 主题分支由 Git 维护者(在其 fork 中)创建,以组织邮件列表中当前的一组传入贡献,并在常规的“git.git 中正在烹饪什么”公告中逐项列出。 要找到主题分支的 tip,请运行 git log --first-parent master..seen 并查找合并提交。 此提交的第二个父级是主题分支的 tip。

选择正确起点的一个指导原则是:通常,始终将您的工作基于与您的更改相关的最旧的集成分支(请参阅 gitworkflows[7] 中的“向上合并”)。 此原则的含义是,对于绝大多数情况,新工作的起点应该是 maintmaster 的最新 HEAD 提交,基于以下情况

  • 如果您要修复已发布版本中的错误,请使用 maint 作为起点(这可能意味着您必须在不使用最近出现在 master 但在已发布版本中不可用的最新 API 功能的情况下修复问题)。

  • 否则(例如,如果您要添加新功能),请使用 master

注意
在特殊情况下,在旧版本中引入的错误可能必须为远早于最新版本的版本的用户修复。 git describe --contains X 可能会将提交 XX 描述为 v2.30.0-rc2-gXXXXXX,该提交 X 引入了该错误,并且该错误的影响可能如此之大,以至于我们可能需要为 Git 2.30.x 系列发布新的维护版本,而“Git 2.41.0”是当前版本。 在这种情况下,您可能想使用 2.30.x 系列的维护分支的 tip,该 tip 可能在 维护者的“分离”存储库 中的 maint-2.30 分支中可用。

这也意味着,如果您希望您的工作有实际机会晋升为 master,则 nextseen 不是您工作的适当起点。 它们根本不是为用作新工作的基础而设计的; 它们仅用于确保飞行中的主题能够很好地协同工作。 这就是为什么 nextseen 都经常与邮件列表中的传入补丁重新集成,并且强制推送以替换其先前版本。 如果一个主题字面上建立在 next 之上,则无法将其合并到 master 中,而不会拖入 next 中的所有其他主题,其中一些主题可能尚未准备就绪。

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

在真正特殊的情况下,您绝对必须依赖于 next 中已经存在的但不在 master 中的少数几个主题分支,您可能需要通过 fork master 并将所需的主题分支合并到其中来创建您自己的自定义基础分支。 然后,您可以在此基础分支之上工作。 但是请记住,此基础分支仅对您私下已知。 因此,当您准备将补丁发送到列表时,请确保在您的求职信中说明您是如何创建它的。 这条关键信息将使其他人能够在其末尾重新创建您的基础分支,以便他们可以试用您的工作。

最后,请注意,系统的某些部分具有专用的维护者及其自己的单独源代码存储库(请参阅下面的“子系统”部分)。

为逻辑上独立的更改创建单独的提交。

除非你的补丁非常简单,否则你不应该发送一个在你工作目录和你提交头之间生成的补丁。相反,始终提交一个包含完整提交信息的 commit,并从你的仓库生成一系列补丁。这是一个很好的习惯。

对你的更改给出详细的解释,以便人们能够判断它是否是一件好事,而无需阅读实际的补丁文本来确定代码如何实现解释中承诺的功能。

如果你的描述开始变得太长,这表明你可能需要将你的 commit 分解成更细粒度的块。话虽如此,能够清楚地描述帮助审查者检查补丁以及帮助未来的维护者理解代码的那些东西的补丁,才是最漂亮的补丁。那些在主题中很好地总结要点,并描述更改的动机、更改采用的方法,以及如果相关,此版本与先前版本有何重大差异的描述,都是很好的。

确保你对你正在修复的 bug 进行了测试。有关指导,请参阅 t/README

当添加一个新功能时,确保你有新的测试来表明该功能在应该触发新行为时会触发,并且在不应该触发时不会触发。在任何代码更改之后,确保整个测试套件通过。在修复 bug 时,确保你有新的测试,如果其他人意外地破坏了你修复的内容,这些测试将会失败,以避免回归。此外,尝试将你的工作合并到 *next* 和 *seen*,并确保测试仍然通过;其他人的仍在进行中的 topics 可能会与你正在你的 topic 中尝试做的事情发生意外的交互。

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

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

目前,我们在拼写和语法上混合使用了美国和英国英语规范,这有点不幸。但是,一个大的补丁会触及所有文件,仅仅为了纠正不一致之处是不受欢迎的。由此类补丁可能导致与其他更改的潜在冲突是不值得的。我们更喜欢逐步协调这些不一致之处,倾向于使用美式英语,以小的、易于理解的补丁,作为在附近做一些其他实际工作的副作用(例如,为了清晰起见而重写一段话,同时将英式英语拼写改为美式英语)。明显的排版修复更受欢迎(“teh → “the””),最好作为独立于其他文档更改的单独补丁提交。

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

好好描述你的更改。

解释你的更改的日志消息与更改本身一样重要。你的代码可以用清晰的内联注释编写,以充分解释它如何与周围的代码一起工作,但那些将来需要修复或增强你的代码的人将需要知道为什么你的代码会这样做,原因如下:

  1. 你的代码可能正在做一些与你想要做的不同的事情。写下你实际想要实现的目标将帮助他们修复你的代码,并使其执行它应该执行的操作(此外,在编写日志消息以总结其背后的想法时,你经常会发现自己的错误)。

  2. 你的代码可能正在做一些仅对你的直接需求必要的事情(例如,“对目录执行 X”,而没有实现甚至设计对文件执行什么)。写下你为什么排除代码没有做的事情将有助于指导未来的开发人员。写下“我们对目录执行 X,因为目录具有特征 Y”将帮助他们推断“哦,文件也具有相同的特征 Y,所以也许对它们执行 X 也有意义?”。说“我们不对文件执行相同的 X,因为……”将帮助他们决定推理是否合理(在这种情况下,他们不会浪费时间扩展你的代码来覆盖文件),或者以不同的方式推理(在这种情况下,他们可以解释为什么他们扩展你的代码来覆盖文件)。

你的日志消息的目标是传达你的更改背后的原因,以帮助未来的开发人员。审查者还将确保你提出的日志消息能够很好地服务于此目的。

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

  • doc: clarify distinction between sign-off and pgp-signing

  • githooks.txt: improve the intro section

如果对使用哪个标识符有疑问,请对你正在修改的文件运行 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 出现在句子中间,我们也用全部大写字母拼写它。

正文应提供有意义的提交消息,其中:

  1. 解释了更改尝试解决的问题,即没有更改的当前代码有什么问题。

  2. 证明了更改解决问题的方式,即更改后的结果为什么更好。

  3. 考虑过但被丢弃的替代解决方案,如果有的话。

描述现状的问题陈述是用现在时写的。写“代码在给定输入 Y 时执行 X”,而不是“代码在给定输入 X 时过去常常执行 Y”。你不需要说“目前”---问题陈述中的现状是关于没有你的更改的代码,按照项目约定。

用祈使语气描述你的更改,例如 “make xyzzy do frotz” 而不是 “[This patch] makes xyzzy do frotz” 或 “[I] changed xyzzy to do frotz”,就像你正在给代码库下达命令以更改其行为一样。尽量确保你的解释可以在没有外部资源的情况下被理解。不要给出邮件列表存档的 URL,总结讨论的相关要点。

您可能想参考历史记录中“更稳定”部分(即在 maintmasternext 等分支上)中的另一个提交的原因有以下几个:

  1. 引入了你正在修复的 bug 的根本原因的提交。

  2. 引入了你正在增强的功能的提交。

  3. 当你在 trial merge你的工作到 nextseen 进行测试时,与你的工作发生冲突的提交。

当你引用更稳定的分支(如 mastermaintnext)上的提交时,使用 “abbreviated hash (subject, date)” 格式,如下所示:

	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
	noticed that ...

gitk 的“复制提交引用”命令可以用来获得这种格式(主题包含在一对双引号中),或者 git show 的这种调用:

	git show -s --pretty=reference <commit>

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

	git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>

通过添加你的 Signed-off-by trailer 来证明你的工作。

为了改进对谁做了什么事情的跟踪,我们要求你通过“签署”你的补丁来证明你编写了该补丁,或者有权根据与我们相同的许可证传递它。没有签名,我们无法接受你的补丁。

如果(且仅当)你证明了下面的 D-C-O

开发者原创证书 1.1

通过对此项目做出贡献,我证明:

  1. 该贡献完全或部分由我创建,并且我有权根据文件中指示的开源许可证提交它;或者

  2. 该贡献基于先前的工作,据我所知,该工作已获得适当的开源许可的覆盖,并且我有权在该许可下提交该工作,并进行修改,无论该工作完全或部分由我创建,根据相同开源许可证(除非我被允许在不同的许可证下提交),如文件中所示;或者

  3. 该贡献由其他人直接提供给我,他们证明了 (a)、(b) 或 (c),并且我没有修改它。

  4. 我理解并同意本项目和贡献是公开的,并且贡献的记录(包括我提交的所有个人信息,包括我的签名)将被无限期地维护,并且可以根据本项目或所涉及的开源许可证进行重新分发。

你向你的 commit 添加一个 “Signed-off-by” trailer,如下所示:

	Signed-off-by: Random J Developer <random@developer.example.org>

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

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

此过程最初来自 Linux 内核项目,因此我们的规则与他们的规则非常相似,但签名你的补丁究竟意味着什么因项目而异,因此可能与你习惯的项目不同。

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

如果你愿意,你可以添加额外的 trailers 在最后:

  1. Reported-by: 用于表彰发现补丁尝试修复的 bug 的人。

  2. Acked-by: 表示更熟悉补丁尝试修改的区域的人喜欢该补丁。

  3. Reviewed-by: 与其他 trailers 不同,只能由审查者自己在详细分析后完全满意该补丁时提供。

  4. Tested-by: 用于指示该人应用了该补丁并发现它具有所需的效果。

  5. Co-authored-by: 用于指示人们在提交补丁之前交换了补丁草案。

  6. Helped-by: 用于表彰为更改建议想法而没有以补丁形式提供精确更改的人。

  7. Mentored-by: 用于表彰某人在指导计划(例如 GSoC 或 Outreachy)中帮助开发补丁的人。

  8. Suggested-by: 用于表彰某人提出了补丁的想法。

虽然在必要时你也可以创建自己的 trailer,但我们鼓励你使用上面突出显示的本项目中的常用 trailer 之一。

仅将 trailer 的第一个字母大写,即倾向于使用 "Signed-off-by" 而不是 "Signed-Off-By",使用 "Acked-by:" 而不是 "Acked-By"。

使用 Git 工具从你的提交生成补丁。

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

如果你的补丁涉及文件重命名,你不必害怕使用 git diffgit format-patch-M 选项。接收端可以很好地处理它们。

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

注意
从审查你的补丁的人的角度来看,master 分支是默认的预期起点。因此,如果你选择了不同的起点,请在你的 cover letter 中说明此选择。

发送你的补丁。

选择你的审查者

注意
可能与安全相关的补丁应私下提交给 Git Security 邮件列表[1],而不是公共邮件列表。

将你的补丁发送到邮件列表,并在 "cc:" 中列出涉及你所接触领域的人(contrib/contacts/ 中的 git-contacts 脚本[2] 可以帮助识别他们),以征求评论和审查。此外,当你尝试将你的 topic 合并到 nextseen 时,你可能已经注意到其他人的工作与你的更改冲突。很有可能这些人非常了解你所接触的领域。

如果你正在使用 send-email,你可以像这样将 git-contacts 的输出传递给它

	git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch

在列表达成共识认为应用该补丁是个好主意后,重新发送它,将 "To:" 设置为维护者[3],并将 "cc:" 设置为列表[4] 以供包含。当维护者没有大量参与讨论,而是将审查留给受信任的其他人时,这尤其重要。

不要忘记根据需要添加 trailer,例如 Acked-by:Reviewed-by:Tested-by: 行,以表彰帮助你的补丁的人,并在发送此类最终版本以供包含时 "cc:" 他们。

format-patchsend-email

如果可能,学习使用 format-patchsend-email。这些命令针对发送补丁的工作流程进行了优化,避免了许多现有电子邮件客户端(通常针对 "multipart/*" MIME 类型电子邮件进行了优化)可能使你的补丁无法使用的方式。

注意
在这里,我们概述了使用 format-patchsend-email 的过程,但你也可以使用 GitGitGadget 发送你的补丁(请参阅 MyFirstContribution)。

Git 邮件列表中的人员需要能够阅读和评论你提交的更改。对于开发人员来说,能够使用标准电子邮件工具“引用”你的更改,以便他们可以评论代码的特定部分非常重要。因此,每个补丁都应“内联”地在单独的消息中提交。

补丁系列的后续版本和其他相关补丁应分组到它们自己的电子邮件线程中,以帮助读者找到系列的所有部分。为此,将它们作为对额外的“cover letter”消息(见下文)、第一个补丁或相应的先前补丁的回复发送。这是一个关于如何提交补丁系列更新版本的分步指南

如果你的日志消息(包括 Signed-off-by trailer 上的你的姓名)在 ASCII 中不可写,请确保你以正确的编码发送消息。

警告
警惕你的 MUA 的自动换行损坏你的补丁。不要剪切粘贴你的补丁;如果不小心,你可能会丢失制表符。

通常的约定是在你的主题行前加上 [PATCH]。这让人们可以轻松地区分补丁和其他电子邮件讨论。还鼓励在方括号中使用除 PATCH 之外的标记来描述补丁的性质。例如,[RFC PATCH](其中 RFC 代表“request for comments”)通常用于表示补丁在被接受之前需要进一步讨论,[PATCH v2]、[PATCH v3] 等通常在你发送先前发送内容的更新时看到。

git format-patch 命令遵循当前的最佳实践来格式化电子邮件消息的正文。在补丁的开头应该是你的提交消息,以 Signed-off-by trailer 结尾,然后是一行由三个短划线组成的行,然后是 diffstat 信息和补丁本身。如果你正在转发来自其他人的补丁,可以选择在电子邮件消息的开头,就在提交消息开始之前,放置一个 "From: " 行来命名该人。要将主题中的默认 "[PATCH]" 更改为 "[<text>]",请使用 git format-patch --subject-prefix=<text>。作为快捷方式,你可以使用 --rfc 代替 --subject-prefix="RFC PATCH",或使用 -v <n> 代替 --subject-prefix="PATCH v<n>"

你通常想要添加关于补丁的额外解释,而不是提交消息本身。将此类“cover letter”材料放在三划线行和 diffstat 之间。对于需要多次迭代审查和讨论的补丁,可以将每次迭代之间的更改说明保存在 Git-notes 中,并通过 git format-patch --notes 在三划线行之后自动插入。

这是实验性的.

在发送主题时,你可以提出一个应该出现在“What’s cooking”报告中的一段摘要,以便在选择主题时解释该主题。如果你选择这样做,请编写一个 2-5 行的段落,该段落将很好地适合我们的发行说明(请参阅 Documentation/RelNotes/* 文件中的许多项目符号条目作为示例),并使其成为 cover letter 的第一段。对于单补丁系列,请使用三划线行和 diffstat 之间的空间,如前所述。

不要将补丁作为 MIME 附件附加,无论是否压缩。不要让你的电子邮件客户端发送 quoted-printable。不要让你的电子邮件客户端发送 format=flowed,这会破坏你的补丁中的空格。许多流行的电子邮件应用程序并不总是将 MIME 附件作为纯文本传输,因此无法评论你的代码。MIME 附件也需要更多的时间来处理。这不会降低你的 MIME 附件更改被接受的可能性,但它会使它更有可能被推迟。

例外:如果你的邮件程序正在损坏补丁,那么有人可能会要求你使用 MIME 重新发送它们,这是可以的。

不要 PGP 签名你的补丁。很可能,你的维护者或列表中的其他人不会拥有你的 PGP 密钥,也不会费心获取它。你的补丁不是由你是谁来判断的;来自未知来源的一个好的补丁比来自已知、受人尊敬的来源的补丁做得不好或做不正确的事情更有可能被接受。

如果你真的非常非常想做一个 PGP 签名的补丁,请将其格式化为 "multipart/signed",而不是以 -----BEGIN PGP SIGNED MESSAGE----- 开头的 text/plain 消息。那不是 text/plain,而是其他的东西。

处理冲突和迭代补丁

在修改对补丁所做的更改时,重要的是要承认与其他正在进行的主题发生冲突的可能性。为了有效地应对这些潜在的冲突,请遵循下面概述的建议步骤

  1. 基于合适的基分支构建,请参阅上面的部分,并 format-patch 该系列。如果你正在进行 "rebase -i" 就地更新,从上一轮开始,这将重用之前的基,因此 (2) 和 (3) 可能会变得微不足道。

  2. 找到上一轮排队的基础

    $ mine='kn/ref-transaction-symref'
    $ git checkout "origin/seen^{/^Merge branch '$mine'}...master"
  3. 应用你的 format-patch 结果。有两种情况

    1. 一切都干净地应用,并且测试良好。转到 (4)。

    2. 事情应用得干净,但构建失败或测试失败,或者事情应用得不干净。

      在后一种情况下,你存在来自旧基础和你用于在 (1) 中构建的基础之间差异的文本或语义冲突。确定导致中断的原因(例如,自从 (2) 使用的基础到 (1) 使用的基础以来,可能已经合并了一个或两个主题)。

      检出最新的 *origin/master*(可能比 (2) 使用的基础更新),"merge --no-ff" 你新依赖的主题,并将合并结果用作基础,重新构建该系列并再次测试。从上次此类合并运行 format-patch 到你的主题的顶端。如果你做了

      $ git checkout origin/master
      $ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar
      $ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux
      ... rebuild the topic ...

      那么你只需在这些“准备地面”合并之上格式化你的主题,例如

      $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD

      不要忘记在 cover letter 中写下你这样做过,包括你在 *master* 之上的基础中拥有的主题。然后转到 (4)。

  4. 尝试将你的主题合并到 *next* 和 *seen* 中,例如

    $ git checkout --detach 'origin/seen'
    $ git revert -m 1 <the merge of the previous iteration into seen>
    $ git merge kn/ref-transaction-symref

    如果你的主题的先前迭代已经位于 *seen* 中(如本例中所示),则需要“revert”。你可以选择从头开始重建 master..origin/seen,同时排除你之前的迭代,这可能会更密切地模拟维护者端的发生情况。

    此试用合并可能会发生冲突。它主要是为了查看 *其他* 主题可能与你的主题发生的冲突。换句话说,你不必依赖它来使你的主题在 *master* 上工作。如果你的主题在其他主题之前进入 *next*,那么解决冲突可能会成为其他主题所有者的工作。

    在 cover letter 中记下你看到的冲突。你不一定需要解决它们,但这是一个了解其他人在相关领域做什么的好机会。

    $ git checkout --detach 'origin/next'
    $ git merge kn/ref-transaction-symref

    这是为了查看你的主题与其他已经在烹饪中的主题发生的冲突。如果 (3)-2 在更新的 master 之上,加上从 *next* 中获取的依赖主题,准备了一个基础,那么这不应该发生冲突。除非上下文很严重(一种判断方法是尝试使用你的旧迭代进行相同的试用合并,这可能会以类似的方式发生冲突),否则期望它将在维护者端处理(如果变得难以管理,我会在收到你的补丁时要求重新基于)。

具有专用维护者的子系统

系统的某些部分有自己的专用维护者,并拥有自己的存储库。

  • git-gui/ 来自 git-gui 项目,由 Johannes Sixt 维护

    https://github.com/j6t/git-gui
    Contibutions should go via the git mailing list.
  • gitk-git/ 来自 gitk 项目,由 Johannes Sixt 维护

    https://github.com/j6t/gitk
    Contibutions should go via the git mailing list.
  • po/ 来自本地化协调员 Jiang Xin

    https://github.com/git-l10n/git-po/

对这些部分的补丁应基于他们的树。

  • 由 Jean-Noël Avila 领导的“Git 文档翻译”项目翻译了我们的文档页面。他们的工作成果与本项目分开维护,而不是作为我们树的一部分

    https://github.com/jnavila/git-manpages-l10n/

GitHub CI

在 GitHub 上拥有一个帐户后,您可以使用 GitHub CI 在 Linux、Mac 和 Windows 上测试您的更改。 请参阅 https://github.com/git/git/actions/workflows/main.yml,了解最近 CI 运行的示例。

请按照以下步骤进行初始设置

  1. https://github.com/git/git Fork 到您的 GitHub 帐户。 您可以在此处找到有关如何 Fork 的详细说明:https://help.github.com/articles/fork-a-repo/

完成初始设置后,每当您将新更改推送到 GitHub 上 Git 的 Fork 时,CI 都会运行。 您可以在此处监视所有分支的测试状态:https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml

如果某个分支未通过所有测试用例,则它将被标记为红色 x,而不是绿色勾选标记。 在这种情况下,您可以单击失败的作业并导航到 "ci/run-build-and-tests.sh" 和/或 "ci/print-test-failures.sh"。 您还可以下载“Artifacts”,它们是包含 tar(或 zipped)存档的 zip 存档,其中包含与调试相关的测试数据。

然后修复问题并将您的修复推送到您的 GitHub Fork。 这将触发新的 CI 构建,以确保所有测试都通过。

MUA 特定提示

我收到或从列表中选取的一些补丁程序存在常见的损坏模式。 请确保您的 MUA 设置正确,以避免损坏空格。

有关通过将补丁程序通过邮件发送给自己并使用 git-am[1] 应用来检查补丁程序的提示,请参阅 git-format-patch[1] 的“DISCUSSION”部分。

当您执行此操作时,请检查应用补丁程序的试运行所产生的提交日志消息。 如果生成的提交中的内容与您希望看到的完全不一样,那么您的维护者很可能会在应用您的补丁程序时手动编辑日志消息。 诸如“嗨,这是我的第一个补丁。\n”之类的内容(如果您确实想将其放入补丁程序的电子邮件中),应该放在指示提交消息结束的三划线之后。

Pine

(Johannes Schindelin)

I don't know how many people still use pine, but for those poor
souls it may be good to mention that the quell-flowed-text is
needed for recent versions.

... the "no-strip-whitespace-before-send" option, too. AFAIK it
was introduced in 4.60.

(Linus Torvalds)

And 4.58 needs at least this.

diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
Author: Linus Torvalds <torvalds@g5.osdl.org>
Date:   Mon Aug 15 17:23:51 2005 -0700

    Fix pine whitespace-corruption bug

    There's no excuse for unconditionally removing whitespace from
    the pico buffers on close.

diff --git a/pico/pico.c b/pico/pico.c
--- a/pico/pico.c
+++ b/pico/pico.c
@@ -219,7 +219,9 @@ PICO *pm;
	    switch(pico_all_done){	/* prepare for/handle final events */
	      case COMP_EXIT :		/* already confirmed */
		packheader();
+#if 0
		stripwhitespace();
+#endif
		c |= COMP_EXIT;
		break;

(Daniel Barkalow)

> A patch to SubmittingPatches, MUA specific help section for
> users of Pine 4.63 would be very much appreciated.

Ah, it looks like a recent version changed the default behavior to do the
right thing, and inverted the sense of the configuration option. (Either
that or Gentoo did it.) So you need to set the
"no-strip-whitespace-before-send" option, unless the option you have is
"strip-whitespace-before-send", in which case you should avoid checking
it.

Thunderbird, KMail, GMail

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

Gnus

*Summary* 缓冲区中的“|”可用于将当前消息通过管道传递到外部程序,这是一种驱动 git am 的便捷方法。 但是,如果消息是 MIME 编码的,那么通过管道传递到程序中的是您在解包 MIME 后在 *Article* 缓冲区中看到的表示形式。 这通常不是您想要的,原因有两个。 它倾向于搞乱非 ASCII 字符(最明显的是在人的姓名中),并且也搞乱空格(在补丁程序中是致命的)。 在使用“|”运行管道之前,运行“C-u g”以原始形式显示消息可以解决此问题。


1. Git 安全邮件列表:git-security@googlegroups.com
2. `contrib/` 下的脚本不是核心 `git` 二进制文件的一部分,必须直接调用。 克隆 Git 代码库并运行 `perl contrib/contacts/git-contacts`。
3. 当前维护者:gitster@pobox.com
4. 邮件列表:git@vger.kernel.org
scroll-to-top