提交补丁

初始补丁设计

如果您有一个满足明显需求的简单补丁，您可能可以直接将其写入补丁并提交到 pgsql-hackers 邮件列表，而无需先对其进行设计审查。但总的来说，在将非平凡的更改作为补丁提交之前，应该在 pgsql-hackers 列表中进行讨论（可能在代码编写之前）。

有关一般的编码风格指南，请参阅 开发人员常见问题解答 和 PostgreSQL 编码规范。

首先设计您的界面

问问自己以下问题

• 用户会与这个新功能交互吗？如果是，如何交互？
• 语法是什么？要有想法，并有能力为您坚信的技术决策进行辩护。
• 确切的语义/行为是什么？
• 是否存在任何向后兼容性问题？
• 在开始编码之前，在这个详细级别上获得社区的认可。但并非一定要达成共识。
• 给您发送到 -hackers 列表的电子邮件写一个开头段落，回答这些问题
  • 这是我试图解决的问题
  • 这是它目前正在做的事情
  • 这是它将要做的。

最重要的是，让社区中的人尽早参与您的想法，以便您可以在早期对半成品的想法进行审查，而不是在真空环境中创建东西。同样，如果您专注于您可以完美执行的想法中最小的部分，那么进展更容易，并且可以使补丁保持集中。抵制一次性构建大型补丁的诱惑，因为这些补丁不太可能得到有用的审查，因此也就不太可能被提交。您应该查看您的补丁最终将如何 被审查，以便确保审查很可能成功。

帮我们省去代码格式化的麻烦

请阅读 PostgreSQL 编码规范。另外，请遵循相邻代码的风格！最终，我们依靠 pgindent 来维护源代码中一致的风格。 Tom 的建议 阐明了一些您可能会遇到的更棘手的情况。 创建干净的补丁 提供了有关如何进行自我审查和改进补丁以修复代码格式问题的分步指南。

命名事物（代码变量、函数等）很重要，如果存在疑问，请让其他人帮助您命名。我们倾向于使用 驼峰式命名法 或下划线：thisStyleIsOkay 或 this_is_okay_too。

一般来说，尝试与周围的代码融为一体。不要使用 #ifdef 来启用您的更改。注释用于澄清和解释 为什么 问题，而不是用以区分您的代码与周围环境或重新说明代码正在做什么。在您的补丁之后，代码应该看起来像是始终以这种方式编写，而不是新功能事后才被添加。

请删除所有无关的空格。 使用 git diff --check（或 git show --check 用于最新提交）可以使伪造的空格脱颖而出。

补丁提交

一旦您认为您的补丁已经完成，请通读您将发送到邮件列表的完整补丁。确保补丁没有错误地包含意外更改（例如空格更改、测试代码、#ifdef 0'd out 块等）。然后，应该通过电子邮件将补丁提交到 pgsql-hackers 邮件列表。在那时，或者在您等待初始反馈之后，您也应该将其添加到下一个 CommitFest 的页面中。

通常，更改应作为包含所有被触及文件的单个补丁提交。如果补丁很大，并且可以逻辑地分成不同的、可单独提交的部分，以便更容易审查，并在适用时描述一个清晰的应用顺序，那么对于更复杂的补丁，审阅者更容易处理。格式化补丁的最简单方法是使用 git format-patch；有关该主题的更深入讨论，请参阅 如何通过电子邮件提交补丁，2023 年版，以及 创建干净的补丁，以获得更多关于使您的补丁更便于审阅者友好地使用的心得。

请注意，PostgreSQL 为其代码使用 BSD/MIT 风格的许可证。通过将补丁发布到公共 PostgreSQL 邮件列表，您正在授予 PostgreSQL 全球开发组在 PostgreSQL 许可证 下分发您的补丁的不可撤销权利。

请在提交的每个补丁中包含以下所有信息；请不要像填写表格一样格式化您的电子邮件。

• 项目名称。
• 唯一可识别的文件名，以便我们能够区分您的 v1 和 v24。
• 补丁在简短的段落中做了什么。
• 补丁是用于讨论还是用于应用（参见下面的 WIP 说明）
• 补丁针对哪个分支（通常是 master）。有关 PostgreSQL 中分支的更多信息，请参阅 使用后退分支。
• 它是否成功编译和测试，以便我们知道没有明显的东西被破坏。
• 它是否包含任何特定于平台的项目，如果是，它是否已在其他平台上测试过。
• 确认补丁包含 回归测试 以检查新功能是否按描述工作。
• 包含有关如何使用新功能的文档，包括示例。有关更多信息，请参阅 文档文档。
• 描述您的补丁对性能的影响（如果有）。
• 尝试包含几行关于您为什么选择以特定方式做事的原因，而不是让您的审阅者猜测发生了什么。这可以通过代码注释来完成，但也可能是额外的审阅者指南，或添加到代码目录中某个 README 文件中。
• 如果您的补丁解决了 待办事项 项目，请在您的电子邮件中给出待办事项的名称。这样，审阅者就知道如果您的补丁被应用，则需要将该项目标记为已完成。

对于早期的补丁，那些不打算具有提交质量的补丁，将其清楚地标记为这样很有帮助，以便进行适当的审查风格。缩写 WIP（“正在进行中”）是用于附加到不打算作为提交候选，而是用于设计反馈的补丁的标准缩写。在您的电子邮件主题行和 CF 应用程序中的匹配描述中将您的补丁标记为 WIP 将建议审阅者更多地关注一般方法，而不是代码风格等东西，这些东西通常可以在补丁生命周期的早期阶段被忽略。

补丁被退回的原因

提交补丁只是使其被提交的第一步。很少有补丁是完全按照最初提交的样子提交的，即使是经验丰富的专业开发人员提交的补丁也是如此。对于任何非平凡的补丁，您应该至少计划 3 个版本，然后再最终接受。

补丁被退回而没有获得提交者希望的审查考虑，有一些常见的原因

• 最快的让您的补丁被拒绝的方法是进行不相关的更改。重新格式化没有更改的行，更改您认为措辞不当的不相关的注释，触及对您的更改不必要的代码等。每个补丁都应该具有使其健壮地工作所需的最小更改集。如果您不遵循上面的代码格式建议，请期望您的补丁被退回给您，并附有“遵循代码规范”的反馈，很可能没有其他审查。

• 考虑补丁将如何被审查。审阅者将评估的事项在 审查补丁 中列出。您应该查看此列表并考虑在提交之前您是否会通过它。我们建议新的代码贡献者首先花时间进行审查，这样您已经熟悉此列表和流程。审查指南之所以被使用是因为它们有效；建议在提交补丁之前进行自己的自我审查。

• 性能提升被声称但没有测试用例。性能补丁写起来很有趣，但很难验证。如果补丁旨在提高性能，那么最好包含一些可重现的测试来证明性能的提升。如果审阅者不能在短时间内复制您声称的性能提升，那么您的补丁很可能被退回。不要期望审阅者会觉得您的性能功能非常有趣，以至于他们会构建一个完整的测试套件来证明它有效。您应该在补丁验证过程中完成这项工作，并在提交时包含必要的测试框架。

• 没有包含文档或回归测试。任何没有这两个项目的补丁都自动被视为 WIP 补丁——您可能会得到补丁的审查，但不要期望它被提交。有关如何编写这些测试的更多信息，请参阅 回归测试编写。建议在提交电子邮件中以高层级记录设计。

• 未能解决对此设计的先前批评。许多补丁试图做一些以前尝试过或考虑过的事情，而早期的讨论发现了一种显而易见的方法存在问题。没有说明您的新提交如何解决这些问题，表明您存在相同的问题。 待办事项列表 是一个很好的资源，可以找到有关补丁想法的过去讨论。

所有这些建议项目的目的是确保审查者的时间不会被浪费。您花时间编写代码，但这并不意味着您可以要求审查者花费时间、精力和兴趣。请遵循这些指南并熟悉审查流程。让您自己和他人都感到轻松，这样您的补丁就可以快速、轻松地被接受，并且双方都能以良好的幽默感接受。

该演示文稿如何让您的 PostgreSQL 补丁被接受 提供了一些额外的建议，说明如何提交一个补丁，以便更认真地考虑。

提交时间

为了提高对您的补丁或想法进行正确讨论的几率，请注意社区工作周期。例如，如果您在测试版阶段提交了一个全新的想法，不要感到惊讶，如果没有人关注，因为他们专注于发布工作。请在测试版完成后再回来！

PostgreSQL 开发是按照定期CommitFest 组织的，在此期间，新的开发将停止，以便专注于补丁审查和提交。最好是在偶尔的几个星期内，当有活跃的 CommitFest 时，避免提交新的补丁；您可以通过CommitFest 应用程序 检查时间表。如果您的时间表不允许您等到活跃的 CommitFest 结束，您应该明确地将您的提交标记为用于下一个 CommitFest，而不是当前的 CommitFest，以便清楚地表明它不是要作为活跃审查流程的一部分。此外，请记住，您的补丁的审查可能要等到下一个 CommitFest 开始才会进行，因为每个人都可能忙于为提交自己的补丁做准备。

补丁审查和提交

提交后，补丁可以遵循几种不同的工作流程，最终导致它被提交

工作流程 A

1. 您将补丁发布到 pgsql-hackers
2. 提交者立即将其接管并提交。

工作流程 B

1. 您将补丁发布到 pgsql-hackers
2. 您将补丁添加到开放的 commitfest 队列中
3. 提交者从队列中获取补丁并提交。

在任何这些阶段，您的补丁也可能因技术、风格或其他原因而被拒绝。这些拒绝通常会附带有关是否可以接受该补丁的改进版本的反馈。在这种情况下，您应该考虑根据该反馈更新您的补丁并重新提交。

相互审查抵消义务

PostgreSQL 是一个社区项目，它依赖于同行评审。每个向 CommitFest 提交补丁的人员都应该至少审查另一个补丁。理想情况下，选择的相互审查补丁应该与提交的补丁具有相似的规模和/或范围。提交了一个长达数千行的功能的人不能只审查其他人提交的一个小补丁，然后期望社区满意。这个想法类似于用于平衡温室气体排放的“抵消”概念。

此策略允许项目及时地审查、接受、拒绝或返回每个补丁的反馈。很少有其他开源项目能为处理提交提供这样的保证。如果未能参与审查流程，则 PostgreSQL 社区无法保证您对自身补丁的审查和反馈。在 CommitFest 期间积极审查另一个补丁也有助于保持贡献者的参与，以便他们能够处理对其提交的反馈。在 CommitFest 期间没有经过反馈和修订，很少有提交会被提交。

对于 PostgreSQL 的付费贡献者，此策略意味着您应该向您的赞助商明确说明，进行补丁审查是一项义务。当为开发一项新功能以提交给 PostgreSQL 项目而安排时间和制定计划时，这应该包括审查其他功能的资源，作为其开销的必要部分。

提交后续工作

如何让别人回复你？

您已经向 -hackers 发送了一封电子邮件，但没有人回复。您该怎么办？

• 确保您已将您的补丁添加到开放的 commitfest 队列中。
• 首先审查一个补丁或回复列表中的电子邮件。即使它与您正在做的事情无关。
• 首先提交一个体积小且没有争议的补丁，帮助他们了解您，并让您熟悉整个流程。
• 人们更愿意倾听和与已经做出贡献的人合作。
• 此外，在我们的社区中，如果没有人反对，那么就意味着默认同意。在合理的范围内！

参与社区是一个过程，而不是一个单一事件。

提交补丁更新

在提交先前提交补丁的新版本时，您应该执行一些额外的操作

• 唯一地标识新版本。您可以使用 git format-patch -vN，每次递增 N；或者您可以手动添加递增的数字后缀。使用“.patch”扩展名允许一些审查者更轻松地在他们的电子邮件客户端/代码编辑器中阅读它。

• 确保可以轻松地找到补丁的任何早期讨论，方法是提供指向邮件列表帖子 的 Message-Id 为基础的链接。不要指望每个人都能自己找到之前的提交。您通常可以通过在电子邮件客户端中查找 Message-Id 标头来获取电子邮件的邮件 ID。如果它没有明显显示，请尝试“查看邮件来源”或“查看原始”。