diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 66bc54e6..b98ece34 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -120,6 +120,7 @@ ** xref:master/migration_guide.adoc[迁移指南] * IvorySQL开发者 ** xref:master/contribution/contribution_guide.adoc[贡献指南] +** xref:master/contribution/developer_workflow.adoc[本地开发与测试] ** xref:master/developer_guide.adoc[开发者指南] ** IvorySQL架构设计 *** 查询处理 diff --git a/CN/modules/ROOT/pages/master/contribution/developer_workflow.adoc b/CN/modules/ROOT/pages/master/contribution/developer_workflow.adoc new file mode 100644 index 00000000..1bf9f396 --- /dev/null +++ b/CN/modules/ROOT/pages/master/contribution/developer_workflow.adoc @@ -0,0 +1,290 @@ + +:sectnums: +:sectnumlevels: 5 + + += **本地开发与测试工作流** + +本页给出一条从源码到补丁的完整路径:准备工具、配置与编译、初始化双模式实例、在本机跑三档测试、按社区约定提交补丁。 + +本页出现的命令与终端输出都来自实际执行记录;**本批次没有实测的步骤会明确标注,不会给出伪造的输出**。 + +== 适用范围 + +* 需要改动 C 代码、SQL 回归测试或 TAP 测试的贡献者。 +* 需要在本地复现「Oracle 兼容模式初始化失败」这类问题的贡献者。 + +只做文档修订的读者不需要构建,直接参考 xref:master/contribution/contribution_guide.adoc[贡献指南] 即可。 + +== 前置条件 + +=== 构建依赖 + +各发行版的依赖包清单与安装命令见 xref:master/installation_guide.adoc[安装指南],本页不重复。 + +=== 本页额外要求的工具 + +[cols="1,2"] +|=== +| 工具 | 用途 + +| `git` | 取得源码、生成补丁 +| C 编译器(`gcc` 或 `clang`) | 编译服务端与 contrib 模块 +| `perl` | 运行 TAP 测试;`--enable-tap-tests` 还要求 `IPC::Run` +|=== + +=== 不要用 root 跑测试 + +`initdb` 拒绝以 root 身份运行,因此 `make check`、`make -C src/bin/initdb check` 这类目标必须在普通用户下执行。 + +== 从源码构建 + +=== 取得源码 + +[source,bash] +---- +git clone https://github.com/IvorySQL/IvorySQL.git +cd IvorySQL +---- + +=== 配置 + +[source,bash] +---- +./configure --prefix= --with-uuid=e2fs --enable-tap-tests +---- + +* `` 由自己决定,例如安装指南中使用的 `/usr/local/ivorysql/ivorysql-5`。 +* `--with-uuid` 指定 `contrib/uuid-ossp` 依赖的 UUID 库,可选值只有 `bsd`、`e2fs`、`ossp` 三个。 +* `--enable-tap-tests` 是 TAP 测试的开关;不加这个参数,`make -C src/bin/initdb check` 不会真正跑用例。 + +`configure --help` 中与本节相关的几行原文: + +[source,text] +---- + --enable-debug build with debugging symbols (-g) + --enable-tap-tests enable TAP tests (requires Perl and IPC::Run) + --enable-cassert enable assertion checks (for debugging) + --with-uuid=LIB build contrib/uuid-ossp using LIB (bsd,e2fs,ossp) + --with-ossp-uuid obsolete spelling of --with-uuid=ossp +---- + +`--with-ossp-uuid` 是 `--with-uuid=ossp` 的过时拼写,新脚本不要再用。 + +==== 漏写 `--with-uuid` 的后果 + +`configure` 阶段**不会**报错:没有给这个参数时,脚本直接把值置为 `no`。 + +[source,text] +---- +1127:PGAC_ARG_REQ(with, uuid, [LIB], [build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)]) +1128:if test x"$with_uuid" = x"" ; then +1129- with_uuid=no +1130-fi +1144: AC_MSG_ERROR([--with-uuid must specify one of bsd, e2fs, or ossp]) +---- + +代价出现在 `make` 阶段:`contrib/uuid-ossp/uuid-ossp.c` 会命中一条 `#error`。 + +[source,text] +---- +38-#include +39-#else +40:#error "please use configure's --with-uuid switch to select a UUID library" +41-#endif +---- + +顶层 `GNUmakefile:11` 的 `all` 与 `install` 都会无条件递归 `contrib/uuid-ossp`,所以 `make` 直接停在上面这条 `#error`,`make install` 根本执行不到。 + +=== 编译与安装 + +[source,bash] +---- +make -j$(nproc) +make install +---- + +顶层 `make install` 会连同 contrib 一起安装,`uuid-ossp` 的控制文件、SQL 脚本与共享库都会进入安装树。 + +**只装核心要当心**:`make -C src install` 只安装 `src/` 下的内容,不碰 `contrib/`。这样装出来的安装树服务端可用,但 `share/postgresql/extension/` 里没有 `uuid-ossp`,于是 Oracle 模式的 `initdb` 必然失败;补装方式见文末「常见失败与对应动作」。 + +== 初始化双模式实例 + +=== 两种模式 + +`initdb` 用 `-m` 指定数据库模式,可选 `oracle` 与 `pg`,默认是 `oracle`。 + +[source,bash] +---- +# Oracle 兼容模式(默认) +initdb -D -m oracle + +# 原生 PostgreSQL 模式 +initdb -D -m pg +---- + +两种模式的差别体现在 bootstrap 阶段读取的输入文件:Oracle 模式额外需要 `postgres_oracle.bki`、`preload_ora_misc.sql` 等文件,`pg` 模式只用原生那一套。 + +=== `uuid-ossp` 与两种模式的关系 + +Oracle 模式在初始化末段要加载 `uuid-ossp` 扩展,因此**安装树必须同时具备三件东西**:`extension/uuid-ossp.control`、`extension/uuid-ossp--1.1.sql` 和 pkglib 目录下的 `uuid-ossp` 共享库。`pg` 模式不加载它。 + +逐项删除文件后的实测结果(同一份安装树,每次只动一个文件): + +[cols="1,3,1"] +|=== +| 场景 | 操作 | 退出码 + +| A | 三件套齐备,`initdb -m oracle` | 0 +| B | 删 `uuid-ossp.control`,`initdb -m oracle` | 1 +| C | 删 `uuid-ossp.control`,`initdb -m pg` | 0 +| D | 删 `uuid-ossp--1.1.sql`,`initdb -m oracle` | 1 +| E | 删 `uuid-ossp.so`,`initdb -m oracle` | 1 +|=== + +结论:**Oracle 模式对三件套是硬依赖,`pg` 模式不受影响**。 + +当前 master 的 `initdb` 在 bootstrap 之后才发现扩展缺失,此时数据目录已经建出来、随后被回滚删除,报错也看不出到底缺哪个文件;上游有把这项检查提前到写盘之前的改动,合入后失败会发生在创建数据目录之前。 + +=== `-L` 的语义 + +`initdb -L ` 让 initdb 从 `` 读取它自己的输入文件,等价于覆盖内部的 `share_path`。 + +但它**不改变扩展的解析路径**:`CREATE EXTENSION` 由 post-bootstrap 阶段的后端进程按编译期 `SHAREDIR` 解析。所以不要用 `-L` 去「指向一份临时扩展目录」来绕过扩展缺失,那样只会让 initdb 的输入来源与真正的扩展目录分叉,排查时容易误判。 + +== 本地测试三档 + +三档都要在非 root 用户下执行。三档的耗时与覆盖面依次递增,日常开发通常只需要第一档。 + +=== 第一档:TAP 测试 + +[source,bash] +---- +make -C src/bin/initdb check +---- + +这是最快的一档,只跑 `src/bin/initdb/t/` 下的 Perl 用例。实测尾部输出(本批次使用的源码树上 `t/` 下有三个用例;用例数量会随版本变化): + +[source,text] +---- +# +++ tap check in src/bin/initdb +++ +t/001_initdb.pl ............. ok +t/002_gb18030.pl ............ ok +t/003_uuid_ossp_missing.pl .. ok +All tests successful. +Files=3, Tests=86, 19 wallclock secs ( 0.04 usr 0.01 sys + 7.25 cusr 9.03 csys = 16.33 CPU) +Result: PASS +---- + +这一档的夹具做法值得知道:`make` 会先在 `tmp_install` 里用下面这条命令生成模板, + +[source,bash] +---- +initdb --auth trust --no-sync -m pg --no-instructions --lc-messages=C --no-clean /initdb-template +---- + +再以固定端口跑 `prove`: + +[source,bash] +---- +PGPORT=65432 prove -I ../../../src/test/perl/ -I . t/*.pl +---- + +也就是说 **TAP 的公共模板固定使用 `-m pg`**,与 Oracle 模式无关;要覆盖 Oracle 模式,用例必须自己在临时安装树上初始化实例。 + +=== 第二档:核心回归 + +[source,bash] +---- +make check +---- + +这一档跑 `pg_regress` 的核心回归集。**本批次未实测**,因此本页不粘贴它的尾部输出。 + +=== 第三档:Oracle 兼容回归 + +[source,bash] +---- +make oracle-check-world +---- + +这一档跑 Oracle 兼容相关的回归全集,体量明显大于前两档,建议留给提交前的最后一轮。**本批次同样未实测**,本页不粘贴输出。 + +=== 跑测试的几个注意点 + +* 先跑第一档:它最快,能先暴露 TAP 基础设施(`perl`、`IPC::Run`、`prove`)自身的问题。 +* 结果以 `All tests successful.` 与 `Result: PASS` 为准;出现 `Dubious`、`Failed` 时要打开对应日志逐个排查。 +* 各档产生的实例与数据目录都在自己的 `tmp_check/` 下,可以整体删除,不必手工清理。 + +== 提交补丁 + +=== 提交信息风格 + +本仓库的提交标题遵循 `area: imperative summary`:区域名小写、冒号、紧跟祈使句、结尾不加句号。现有提交就是范例: + +[source,text] +---- +initdb: fail early with an actionable error when Oracle mode lacks uuid-ossp +initdb: add TAP coverage for the Oracle mode uuid-ossp check +initdb: list every --with-uuid value in the hint and check the TAP exit status +---- + +正文写清「为什么改」「改了什么」和「怎么验证的」,验证部分尽量贴上实际跑过的命令与结果。 + +=== AI 协作声明 + +使用 AI 工具辅助编写代码或文档时,提交信息里要加两条声明: + +[source,text] +---- +Assisted-by: AGENT_NAME:MODEL_VERSION +Percentage of AI-generated code: xx% +---- + +`AGENT_NAME` 是 AI 工具或框架的名字,`MODEL_VERSION` 是具体模型版本,例如: + +[source,text] +---- +Assisted-by: Claude:4.6 +Assisted-by: GitHub:Copilot +Assisted-by: OpenAI:gpt-4 +---- + +另一条纪律:**AI 工具不得添加 `Signed-off-by` 标签**。只有人类才能在法律上认证开发者原创证书(DCO),提交者要自己审查全部 AI 生成内容、自己签名,并对贡献负全责。 + +=== 生成并发送补丁 + +[source,bash] +---- +# 导出整个分支相对 master 的补丁 +git format-patch origin/master + +# 只要最后一个提交 +git format-patch -1 HEAD +---- + +导出的 `.patch` 可以作为邮件附件发送给邮件列表,也可以把分支推送到自己的 fork 后开 Pull Request。 + +=== 签署 CLA + +提交代码或文档之前需要先签署贡献者许可协议,签署方式与两条下载链接见 xref:master/contribution/contribution_guide.adoc[贡献指南] 的「签署 CLA」一节。未签署 CLA 的 Pull Request 无法进入评审阶段。 + +== 常见失败与对应动作 + +[cols="2,2,2"] +|=== +| 现象 | 原因 | 动作 + +| `make` 停在 `uuid-ossp.c:40:2: error: #error "please use configure's --with-uuid switch to select a UUID library"` | 配置时没给 `--with-uuid` | 重新执行 `./configure --with-uuid=e2fs ...`(或改用 `ossp`、`bsd`) +| `configure` 提示缺少 `IPC::Run` | TAP 测试依赖没装 | Debian/Ubuntu:`sudo apt install libipc-run-perl` +| Oracle 模式 `initdb` 退出码 1,报错指向 `uuid-ossp` 扩展 | 安装树缺三件套,常见于 `make -C src install` 的部分安装 | `make -C contrib/uuid-ossp install` 补装,或改用 `-m pg` +| `make check` 一开始就失败 | 以 root 身份执行 | 换普通用户重跑 +|=== + +== 小结 + +. 用 `--with-uuid` 指定 UUID 库,用 `--enable-tap-tests` 打开 TAP。 +. 顶层 `make install` 才会把 contrib 一起装上。 +. `-m oracle` 需要 `uuid-ossp` 三件套,`-m pg` 不需要。 +. 每天至少跑一次 `make -C src/bin/initdb check`,提交前再跑回归全集。 +. 提交信息按 `area: imperative summary` 写,用了 AI 就补上两条声明。 diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index a2026117..ac18a074 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -119,6 +119,7 @@ ** xref:master/migration_guide.adoc[Migration] * IvorySQL Developers ** xref:master/contribution/contribution_guide.adoc[Contribution Guide] +** xref:master/contribution/developer_workflow.adoc[Local Development and Testing] ** xref:master/developer_guide.adoc[Developer] * IvorySQL Architecture Design ** Query Processing diff --git a/EN/modules/ROOT/pages/master/contribution/developer_workflow.adoc b/EN/modules/ROOT/pages/master/contribution/developer_workflow.adoc new file mode 100644 index 00000000..f2a39c22 --- /dev/null +++ b/EN/modules/ROOT/pages/master/contribution/developer_workflow.adoc @@ -0,0 +1,290 @@ + +:sectnums: +:sectnumlevels: 5 + + += **Local Development and Testing Workflow** + +This page walks through the full path from source code to a submitted patch: prepare the tools, configure and build, initialize clusters in both modes, run the three tiers of tests locally, and submit the patch following the community conventions. + +Every command and every terminal output on this page comes from an actual run. **Steps that were not measured in this batch are called out explicitly; no output on this page is invented.** + +== Scope + +* Contributors who change C code, SQL regression tests, or TAP tests. +* Contributors who need to reproduce problems such as "Oracle-compatible mode fails during initialization". + +Readers who only revise documentation do not need a build; see the xref:master/contribution/contribution_guide.adoc[Contribution Guide] instead. + +== Prerequisites + +=== Build dependencies + +The package list for each distribution and its installation commands are in the xref:master/installation_guide.adoc[Installation Guide]; this page does not repeat them. + +=== Additional tools required by this page + +[cols="1,2"] +|=== +| Tool | Purpose + +| `git` | Get the sources, generate patches +| C compiler (`gcc` or `clang`) | Build the server and contrib modules +| `perl` | Run TAP tests; `--enable-tap-tests` also requires `IPC::Run` +|=== + +=== Do not run tests as root + +`initdb` refuses to run as root, so targets such as `make check` and `make -C src/bin/initdb check` must be run by a regular user. + +== Building from Source + +=== Get the sources + +[source,bash] +---- +git clone https://github.com/IvorySQL/IvorySQL.git +cd IvorySQL +---- + +=== Configure + +[source,bash] +---- +./configure --prefix= --with-uuid=e2fs --enable-tap-tests +---- + +* `` is your choice, for example the `/usr/local/ivorysql/ivorysql-5` prefix used in the Installation Guide. +* `--with-uuid` selects the UUID library used by `contrib/uuid-ossp`; the only accepted values are `bsd`, `e2fs`, and `ossp`. +* `--enable-tap-tests` is the switch for TAP tests. Without it, `make -C src/bin/initdb check` does not actually run the cases. + +The relevant lines from `configure --help`: + +[source,text] +---- + --enable-debug build with debugging symbols (-g) + --enable-tap-tests enable TAP tests (requires Perl and IPC::Run) + --enable-cassert enable assertion checks (for debugging) + --with-uuid=LIB build contrib/uuid-ossp using LIB (bsd,e2fs,ossp) + --with-ossp-uuid obsolete spelling of --with-uuid=ossp +---- + +`--with-ossp-uuid` is the obsolete spelling of `--with-uuid=ossp`; do not use it in new scripts. + +==== What happens if --with-uuid is omitted + +`configure` does **not** fail: when the option is absent, the script simply sets the value to `no`. + +[source,text] +---- +1127:PGAC_ARG_REQ(with, uuid, [LIB], [build contrib/uuid-ossp using LIB (bsd,e2fs,ossp)]) +1128:if test x"$with_uuid" = x"" ; then +1129- with_uuid=no +1130-fi +1144: AC_MSG_ERROR([--with-uuid must specify one of bsd, e2fs, or ossp]) +---- + +The price is paid during `make`: the translation unit `contrib/uuid-ossp/uuid-ossp.c` hits an `#error`. + +[source,text] +---- +38-#include +39-#else +40:#error "please use configure's --with-uuid switch to select a UUID library" +41-#endif +---- + +Both the `all` and `install` goals in the top-level `GNUmakefile:11` recurse into `contrib/uuid-ossp` unconditionally, so `make` stops at that `#error` and `make install` is never reached. + +=== Build and install + +[source,bash] +---- +make -j$(nproc) +make install +---- + +The top-level `make install` installs contrib as well, so the `uuid-ossp` control file, SQL script, and shared library all land in the installation tree. + +**Be careful with a core-only install**: `make -C src install` installs only what is under `src/` and never touches `contrib/`. The resulting installation tree has a working server, but `share/postgresql/extension/` contains no `uuid-ossp`, so Oracle-compatible `initdb` is guaranteed to fail. See "Common Failures and Fixes" at the end of this page for how to install it afterwards. + +== Initializing Clusters in Both Modes + +=== The two modes + +`initdb` selects the database mode with `-m`. The accepted values are `oracle` and `pg`, and the default is `oracle`. + +[source,bash] +---- +# Oracle-compatible mode (default) +initdb -D -m oracle + +# Native PostgreSQL mode +initdb -D -m pg +---- + +The difference shows up in the input files read during the bootstrap stage: Oracle mode additionally needs files such as `postgres_oracle.bki` and `preload_ora_misc.sql`, while `pg` mode uses only the native set. + +=== How uuid-ossp relates to the two modes + +Oracle mode loads the `uuid-ossp` extension near the end of initialization, so the installation tree **must provide all three pieces**: `extension/uuid-ossp.control`, `extension/uuid-ossp--1.1.sql`, and the `uuid-ossp` shared library under the pkglib directory. `pg` mode does not load it. + +Measured results after deleting one file at a time from the same installation tree: + +[cols="1,3,1"] +|=== +| Case | Action | Exit code + +| A | All three present, `initdb -m oracle` | 0 +| B | Delete `uuid-ossp.control`, `initdb -m oracle` | 1 +| C | Delete `uuid-ossp.control`, `initdb -m pg` | 0 +| D | Delete `uuid-ossp--1.1.sql`, `initdb -m oracle` | 1 +| E | Delete `uuid-ossp.so`, `initdb -m oracle` | 1 +|=== + +In short: **Oracle mode hard-depends on the three pieces, `pg` mode does not.** + +The current master `initdb` only notices the missing extension after the bootstrap stage, at which point the data directory has already been created and is then rolled back and removed, and the message does not say which file is missing. Upstream has a change that moves the check ahead of any disk write; once merged, the failure happens before the data directory is created. + +=== What -L actually does + +`initdb -L ` makes initdb read its own input files from ``; it is equivalent to overriding the internal `share_path`. + +It does **not** change how extensions are resolved: `CREATE EXTENSION` is resolved by the post-bootstrap backend process against the compiled-in `SHAREDIR`. Do not use `-L` to "point at a temporary extension directory" in order to work around a missing extension; that only forks the input location from the real extension directory and misleads diagnosis. + +== Three Tiers of Local Testing + +All three tiers must be run by a regular (non-root) user. Time cost and coverage increase from tier to tier; day-to-day work usually needs only the first one. + +=== Tier 1: TAP tests + +[source,bash] +---- +make -C src/bin/initdb check +---- + +This is the fastest tier; it runs only the Perl cases under `src/bin/initdb/t/`. Measured output (the tree used in this batch had three cases under `t/`; the number varies between versions): + +[source,text] +---- +# +++ tap check in src/bin/initdb +++ +t/001_initdb.pl ............. ok +t/002_gb18030.pl ............ ok +t/003_uuid_ossp_missing.pl .. ok +All tests successful. +Files=3, Tests=86, 19 wallclock secs ( 0.04 usr 0.01 sys + 7.25 cusr 9.03 csys = 16.33 CPU) +Result: PASS +---- + +The fixture behind this tier is worth knowing: `make` first creates a template under `tmp_install` with + +[source,bash] +---- +initdb --auth trust --no-sync -m pg --no-instructions --lc-messages=C --no-clean /initdb-template +---- + +and then runs `prove` on a fixed port: + +[source,bash] +---- +PGPORT=65432 prove -I ../../../src/test/perl/ -I . t/*.pl +---- + +So the **shared TAP template always uses `-m pg`** and has nothing to do with Oracle mode; a case that wants Oracle mode has to initialize its own instance from a temporary installation tree. + +=== Tier 2: core regression + +[source,bash] +---- +make check +---- + +This tier runs the core `pg_regress` suite. It was **not measured in this batch**, so this page does not paste its output. + +=== Tier 3: Oracle-compatible regression + +[source,bash] +---- +make oracle-check-world +---- + +This tier runs the full Oracle-compatibility regression set and is considerably larger than the first two; leave it for the final round before submitting. It was **also not measured in this batch**, so no output is pasted here. + +=== Notes on running the tests + +* Start with tier 1: it is the fastest and surfaces problems with the TAP infrastructure itself (`perl`, `IPC::Run`, `prove`). +* Judge by `All tests successful.` and `Result: PASS`; when `Dubious` or `Failed` appears, open the corresponding log and work through it. +* Each tier leaves its instances and data directories under its own `tmp_check/`, which can be deleted wholesale — no manual cleanup needed. + +== Submitting a Patch + +=== Commit message style + +Commit subjects in this repository follow `area: imperative summary`: a lowercase area name, a colon, an imperative sentence, and no trailing period. Existing commits are the reference: + +[source,text] +---- +initdb: fail early with an actionable error when Oracle mode lacks uuid-ossp +initdb: add TAP coverage for the Oracle mode uuid-ossp check +initdb: list every --with-uuid value in the hint and check the TAP exit status +---- + +The body should state why the change is needed, what it does, and how it was verified; the verification part should paste the commands and results that were actually run. + +=== AI assistance disclosure + +When AI tools helped write code or documentation, add both statements to the commit message: + +[source,text] +---- +Assisted-by: AGENT_NAME:MODEL_VERSION +Percentage of AI-generated code: xx% +---- + +`AGENT_NAME` is the name of the AI tool or framework and `MODEL_VERSION` is the specific model version, for example: + +[source,text] +---- +Assisted-by: Claude:4.6 +Assisted-by: GitHub:Copilot +Assisted-by: OpenAI:gpt-4 +---- + +One more rule: **AI tools must not add `Signed-off-by` tags**. Only a human can legally certify the Developer Certificate of Origin (DCO), so the submitter reviews all AI-generated content, adds the signature, and takes full responsibility for the contribution. + +=== Generating and sending the patch + +[source,bash] +---- +# Export the whole branch relative to master +git format-patch origin/master + +# Export only the last commit +git format-patch -1 HEAD +---- + +The resulting `.patch` files can be sent as mail attachments to the mailing list, or you can push the branch to your own fork and open a Pull Request. + +=== Sign the CLA + +Code and documentation contributions require a signed Contributor License Agreement. The signing process and the two download links are in the "Sign the CLA" section of the xref:master/contribution/contribution_guide.adoc[Contribution Guide]. A Pull Request from a contributor without a signed CLA cannot enter the review stage. + +== Common Failures and Fixes + +[cols="2,2,2"] +|=== +| Symptom | Cause | Action + +| `make` stops at `uuid-ossp.c:40:2: error: #error "please use configure's --with-uuid switch to select a UUID library"` | `--with-uuid` was not passed to configure | Re-run `./configure --with-uuid=e2fs ...` (or `ossp`, `bsd`) +| `configure` reports a missing `IPC::Run` | TAP test dependencies are not installed | Debian/Ubuntu: `sudo apt install libipc-run-perl` +| Oracle mode `initdb` exits with status 1 and the error mentions the `uuid-ossp` extension | The installation tree lacks the three pieces, typically after a core-only `make -C src install` | `make -C contrib/uuid-ossp install`, or use `-m pg` +| `make check` fails immediately | It was run as root | Re-run it as a regular user +|=== + +== Summary + +. Pass `--with-uuid` to select the UUID library and `--enable-tap-tests` to enable TAP. +. Only the top-level `make install` installs contrib. +. `-m oracle` needs the three `uuid-ossp` pieces; `-m pg` does not. +. Run `make -C src/bin/initdb check` at least once a day, and the full regression before submitting. +. Write the commit subject as `area: imperative summary`, and add the two AI statements if AI tools were used.