提交检查清单

这份文档尝试列出 PostgreSQL 项目 提交者 在提交代码前可能想采用的常见检查项。即使是经验丰富的提交者，也可能偶尔会犯一些经典错误。在实际中，很多错误发生在例行流程中跳过某个步骤时，这可能是由看似微不足道的最后一分钟修改造成的。从这些错误中学习很重要。

这份检查清单并不打算让提交者全盘接受。相反，它旨在作为创建您自己的半自定义检查清单的起点。由于您最终的检查清单应该或多或少地机械化地使用，它不应该太长，并且应该组织成各个部分，以便更容易跳过不相关的项目。简而言之，如果将某事作为一项标准实践而一再采用是值得的，那么将其写下来并使其正式化也是值得的。在决定什么对您有意义时，请谨慎行事。

基本检查

• 仔细检查发布版构建的编译器警告。

• make check-world。
  • 您可能希望使用以下方法来加快速度

make -j16 -s install;make -Otarget -j10 -s check-world  && echo "quick make-check world success" || echo "quick make-check world failure"

• 考虑是否需要增加 catversion。

• 不要假设即使您只做了一个微不足道的文档更改，也没有破坏文档构建。
  • 删除 GUC 可能会在发布说明中破坏引用它的实例。
  • 即使是 grep 也可能错过这一点，因为对 GUC 的引用将使用短划线而不是下划线，加上可能的其他变体。

• 根据 https://postgresql.ac.cn/docs/devel/static/error-style-guide.html 验证 err*() 调用。

• 验证 *printf 调用是否包含尾部换行符。

• 拼写检查补丁。

• 验证长行是否最好拆分成几个较短的行。

git diff origin/master | grep -E '^(\+|diff)' | sed 's/^+//' | expand -t4 | awk "length > 78 || /^diff/"

• 对更改的文件运行 pgindent、pgperltidy 和 reformat-dat-files；使更改保持最小。

• 对修改的 Perl 文件运行 pgperlcritic。

• 根据需要更新版本号

CATALOG_VERSION_NO, PG_CONTROL_VERSION, XLOG_PAGE_MAGIC, PGSTAT_FILE_FORMAT_ID

• 根据需要更新函数/其他 OID；

回归测试检查

• 在添加核心回归测试文件时，确保将它们添加到串行和并行计划中。

（但 14 及更高版本仅具有并行计划。）

• 对于任何您正在更新输出的回归测试，查找替代输出文件。
  • 一些测试具有替代输出文件来解决可移植性问题。
  • 大多数情况下，只需将与您自己的平台相关的输出文件的差异应用于其他变体，就能解决问题。
  • 偶尔，您可能需要看看 buildfarm 的说法。

Git 检查

基本

• 在真正推送之前，使用 --dry-run 进行试运行。

• 查看“git status”；是否缺少任何内容？

• 作者和提交者时间戳应该匹配。

如果您习惯于重新设置基线，或使用“git am”应用补丁，这可能是一个问题。通过指定“--pretty=fuller”或更改 git 格式配置，确保您的设置在“git log”中显示两者。使两个时间戳匹配的最简单方法是像这样修改提交

git commit --amend --reset-author

如果您在 git 配置中拥有“autosetuprebase = always”，那么最后一分钟的“git pull”可能会导致重新设置基线，这可能会导致作者和提交者时间戳略有差异。在实践中，作者和提交者时间戳之间的微小差异不被认为是问题。

• 编写日志消息（考虑创建一个 .gitmessage commit.template 模板文件 以便更轻松地做到这一点）

Discussion: https://postgr.es/m/XXXXXXXXXXX
Back-patch depth?
What should the release notes say?
Credit any reviewer.

• 在引用其他提交时，最好使用提交 SHA 的前 9 个字符。少于 9 个字符意味着 HTTP 接口中将没有超链接。超过 9 个字符是不必要的。

• 在提交消息中注意兼容性问题，以便在编写发布说明时可以将其拾取。

• 检查与 master 的合并（不适用于提交）。

• 如果您使用的是带有密码的专用 ssh 密钥，您可能会发现，在完成推送后故意禁用它很有用

$ ssh-add -d ~/.ssh/id_rsa_postgres

回溯和 Git

回溯时，多个分支的提交消息应该相同，以便工具可以识别冗余，以便于编译发布说明和其他类似的事情。

• 获得一致提交元数据的最简单方法是在一开始不要担心 master 分支之外的提交消息。回溯分支上的提交消息最初可以是类似“pending 9.6”的内容。

• 当您完成时，在每个回溯分支上执行以下过程，方法是检出 gitmaster 本地克隆中的每个单独分支，并为具有良好提交消息的 master 分支提交执行此操作

git commit --amend --reset-author -C <commit>

您现在在每个分支上都有相同的提交消息。这意味着 src/tools/git_changelog 实用程序脚本将从每个受影响的本地分支中呈现提交，作为一个逻辑更改。（此脚本用作编写回溯分支发布说明的起点。请注意，“一个逻辑更改”的概念不是标准的 Git 概念。）

• 使用 git push origin : --dry-run 对一次推送所有分支进行试运行。一旦满意，删除 --dry-run 以实际推送。如果您分别推送每个分支，那么 --dry-run 更加重要。

在回溯过程中维护 ABI 兼容性

避免破坏 ABI 兼容性。针对早期版本构建的扩展在较新版本中出现问题是不可接受的。

• 您只能真正更改具有本地链接的函数的签名，可能有一些例外。
• 您不能修改 src/include/*.h 中的任何结构定义。如果必须向结构中添加任何新成员，请将它们放在回溯分支中的末尾。在 master 中拥有不同的结构布局是可以的。即使那样，分配结构的扩展也可能通过对其大小的依赖而出现故障。
• 将新的枚举值移动到末尾。

有关 ABI 保护的更多注意事项，请参见 此消息。

GUC 检查

• 在添加新的 GUC 时，也需要更新 postgresql.conf.sample。

• GUC 组是否正确？

高级冒烟测试

• Valgrind memcheck + “make installcheck”。

• CLOBBER_CACHE_ALWAYS。

• 在执行任何涉及 WAL 日志记录的操作时，请考虑创建一个副本，并确保在 master 运行“make installcheck”时，副本上的 wal_consistency_checking=all 通过。WAL_DEBUG 使任何由此引发的错误更容易隔离。

• “#define COPY_PARSE_PLAN_TREES” 和 “#define WRITE_READ_PARSE_PLAN_TREES” 可以在更改“src/backend/nodes/*”时捕获遗漏或其他错误。

• 各种仅在特定平台上运行的测试，使用 PG_TEST_EXTRA 或 EXTRA_TESTS 环境变量 启用。例如，PG_TEST_EXTRA='ssl' 和 EXTRA_TESTS='collate.linux.utf8' 测试。

• 使用 c.h 中的 -fsanitize=alignment 等检查未对齐访问

• sqlsmith（用于语法更改，以及 ??）

策略

以下列表包含经常被引用但没有得到良好记录的项目策略，这些策略涉及对某些类型的编码/测试/修补模式的处理。可能在某些时候应该将其移动到 postgresql.org，但目前我们将在此处捕获知识。不按特定顺序

• 没有其他可辨别后果的空指针解除引用崩溃不被视为安全问题，应该作为例行错误修复。

• 所有后端全局变量都应该用 **PGDLLIMPORT** 标记，以便它们在 Windows 上对扩展可用。

• 在回归测试运行后不要留下全局对象（角色、订阅、表空间），因为这会在使用 installcheck 模式时弄乱安装。但是，此规则不适用于 TAP 测试，这些测试始终创建临时安装。

• 由回归测试用例创建的瞬态角色应命名为 **regress_something**，以减少对已安装服务器运行此类用例的风险。订阅和表空间也是如此。对于数据库，由于历史原因，规则有所不同：数据库名称必须包含 **regression**。使用 **-DENFORCE_REGRESSION_TEST_NAME_RESTRICTIONS** 编译以获得对此规则的自动检查（并注意一些 buildfarm 机器会这样做）。

• 我们希望保持 最近不再支持（目前，回溯到 9.2）分支在现代系统上可构建。这扩展到修复构建失败、回归测试失败和易于修复的编译器警告。但不要更改不再支持的分支的外部行为。此规则的目的是允许在现代系统上构建旧分支，以便针对旧服务器回溯测试 psql、pg_dump 等；针对与分支的最后一个发布版本不同的行为进行测试毫无意义。允许修复警告的目的是，构建这些分支的人员不必费神重新验证忽略警告是安全的。

• 代码布局和错误消息措辞应遵循主文档中的 PostgreSQL 编码规范。

• 具有 **SQLSTATE XX000**（例如，普通 elog）的内部错误不应从 SQL 触发。如果您认为错误在正常操作中可能可达，请始终添加 errcode() 调用。

• 参考 **src/test/perl/README** 作为编写 TAP 测试的指南。

• 所有“*.h”文件都应该通过 **src/tools/pginclude/headerscheck**，在常规和 **--cplusplus** 模式下。有关详细信息，请参阅它旁边的 README 文件。

• 在添加或更新“src/include/catalog/*.dat”文件中的条目之前，请阅读 系统目录声明和初始内容，特别是关于新 OID 初始选择的规则。

• 无条件地忽略文本文件（如配置文件）中的“\r”，因为人们有时会尝试在 Unix 机器上使用带有 DOS 风格换行符的文件，而在 Unix 机器上，C 库不会将此隐藏起来。

• 每个“*.c”文件都应该从包含 postgres.h、postgres_fe.h 或 c.h 开始，具体取决于情况；然后，任何“*.h”文件都不需要显式包含任何这些文件。此策略的核心原因是，使验证在任何系统头文件（如 ）之前包含 pg_config_os.h 变得容易；如果没有它，由于不同模块在后端的大文件选项方面的差异，我们会在某些平台上遇到可移植性问题。此外，如果“*.h”文件负责选择要包含的这些关键头文件中的哪一个，那么需要在前端或后端编译中包含的“*.h”文件将遇到问题。

• 按照惯例，“*.c”文件应该在 postgres.h/postgres_fe.h/c.h 之后，以及其他 Postgres 头文件之前包含系统和外部库头文件。

• 不要将 EXPLAIN 语句的输出添加到回归测试中，除非使用 COSTS OFF 或通过隐藏确切成本和行数的函数过滤输出。未能做到这一点通常会导致平台相关的故障。

• 数据类型 I/O 函数不得标记为 volatile。（目前，回归测试会检查核心数据类型的此项，但不会检查 contrib。）

发布冻结

请注意即将发布的日期，并避免在计划发布的代码分支上进行提交，从发布日期前星期六中午 UTC 开始，一直持续到发布标签应用完成（通常发生在星期二午夜 UTC 之前）。这段“静默时间”允许在制作 tarballs 之前进行完整的构建场测试，并在初始包装后更正任何打包程序问题报告。安全和发布说明补丁当然会打破这条规则；否则，在未咨询发布团队的情况下，请不要这样做。

受支持的后分支版本通常会根据 此时间表 发布。新分支的 beta、RC 和 GA 版本的日期由 发布管理团队 公布。请注意，除非要从 master 分支发布 beta 版本，否则 master 分支不会冻结。