用途:为 YugabyteDB 的 PostgreSQL 分支 src/postgres 下任何改动提供强制性代码约定。该目录会在每次 PG 大版本升级时重新合并,指南的两个目标是让 YB 差异小、集中且可识别,并让 PG 自有代码与上游逐字节一致,从而让 git 自动合并、只在真实逻辑冲突处产生冲突。
主要能力与规则:为 YB 引入的、在上游上下文中可见的标识符(函数、全局与文件作用域变量、结构体字段、类型、宏、GUC 变量、上游函数新增参数)加 yb 前缀;已有固定前缀的紧跟前缀之后。仅在 YB 代码位于 PG 上下文中时使用 /* YB: ... / 标记。集中放置 YB 代码,通过 / YB includes /、/ YB declarations /、/ YB fields */ 等标记块并与 PG 代码用空行隔开;新 YB 函数放在文件底部;函数参数集中到上游参数列表末尾并加前缀。除排序等强制约束外不交错。PG 自有行尽量保持逐字节一致,仅允许纯粹缩进调整;不要修上游风格、拼写或空白。避免脆弱测试,优先结构性或相对断言,不硬编码会变的 OID 范围与绝对目录版本。注释与提交信息写清 YB 改动的原因。清理只做独立修订,保持行为不变且可机械校验。
使用方式:任何 src/postgres 下的改动都需遵守;可用 src/lint/diff_file_with_upstream.py <file> -b 查看 YB 差异,用 src/lint/upstream_file.py <file> <output-path> 获取固定的上游副本。
限制:旧文件可能普遍违反这些约定,修改时只针对新增或改动的行,不顺手修复他处;涉及测试文件前需阅读 src/postgres/src/test/regress/README;PG 大版本合并进行中时清理需与合并负责人协调。