docs: add ecosystem component adaptation contribution guide

CN/modules/ROOT/nav.adoc

@@ -78,6 +78,7 @@
 ** xref:master/migration_guide.adoc[迁移指南]
 * IvorySQL开发者
 ** xref:master/contribution/community_contribution_guide.adoc[社区贡献指南]
+** xref:master/contribution/ecosystem_contribution_guide.adoc[生态组件适配贡献指南]
 ** xref:master/developer_guide.adoc[开发者指南]
 ** IvorySQL架构设计
 *** 查询处理

CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc

@@ -0,0 +1,324 @@
+:sectnums:
+:sectnumlevels: 5
+
+= 生态组件适配贡献指南
+
+== 概述
+
+IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。
+
+本文档旨在为有意参与生态组件适配的贡献者提供完整的指引，涵盖从选题、环境准备、适配测试、文档编写到提交贡献的全流程。
+
+== 适配范围
+
+以下类型的组件欢迎贡献者进行适配：
+
+* PostgreSQL 社区官方扩展（contrib 模块）
+* 基于 PostgreSQL 扩展机制开发的第三方插件
+* 以独立进程形式与数据库配合工作的周边生态工具，如连接池、代理、中间件等
+
+== 贡献流程
+
+生态组件适配，是将 PostgreSQL 生态组件适配到 IvorySQL 的工作。主要内容包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档，提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库。文档提交后，维护者会按照适配文档中给出的步骤对目标组件进行复现测试，确认测试结果与文档描述一致后，合并该 PR。
+
+具体的选题、测试、文档编写等环节，请参考下面的详细步骤。
+
+=== 第一步：选题与沟通
+
+==== 确认组件未被适配
+
+在开始适配工作之前，请先查阅 xref:master/ecosystem_components/ecosystem_overview.adoc[生态组件适配列表]，确认目标组件是否已完成适配。如果目标组件不在列表中，则继续后面的流程；否则，请重新选择一个未适配的组件。
+
+==== 认领或新建 Issue
+
+在 IvorySQL 仓库的 https://github.com/IvorySQL/IvorySQL/issues[Issue 列表] 中搜索目标组件：
+
+- 如果相关适配 Issue 已存在，先确认其尚未被分配（Assignees 为空），然后点击右上角 Assignees 区域的 `Assign yourself`，将该 Issue 认领给自己；若已被他人认领，请重新选择组件；
+- 如果相关 Issue 尚不存在，则新建一个 `Feature Request` 类型的 Issue，添加 `compatibility` 标签，并分配给自己。新建 Issue 的格式可参考已有的生态组件适配类 Issue：标题格式为 `Ecosystem Integration: <组件名>`，正文用一句话说明要适配的组件及其用途。
+
+维护者会评估该组件是否适合纳入 IvorySQL 生态，并在 Issue 中与您沟通确认。
+
+[TIP]
+建议在 Issue 获得维护者确认后再开始适配工作，避免重复或无效工作。
+
+==== 签署 CLA
+
+在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅 xref:master/contribution/community_contribution_guide.adoc[社区贡献指南] 中的 CLA 签署说明。
+
+=== 第二步：环境准备
+
+==== IvorySQL 环境
+
+请准备一套可用于测试的 IvorySQL 环境，建议满足以下要求：
+
+* IvorySQL 版本：5.0 及以上
+* 操作系统：建议使用 Ubuntu 24.04 (x86_64) 或其他主流 Linux 发行版
+* 安装路径：记录 IvorySQL 的安装路径，后续编译扩展时需要用到 `pg_config` 的路径
+
+[TIP]
+可以通过 IvorySQL 官方提供的 Docker 镜像快速搭建测试环境，参考 xref:master/containerization/docker_podman_deployment.adoc[Docker & Podman 部署]。
+
+==== 编译工具链
+
+根据目标组件的编译方式，准备相应的工具链：
+
+* C/C++ 扩展：需要 gcc、make 等基础编译工具
+* Rust 扩展：需要 cargo、rustc 等 Rust 工具链
+* 其他语言扩展：需要对应语言的运行环境
+
+=== 第三步：适配测试
+
+生态组件适配的目标分为两个层面：
+
+- PG 模式：组件必须完全可用。
+- Oracle 兼容模式：应尽可能做到完全可用；若无法完全可用，至少应保证主要功能可以正常运行。对于底层机制与 Oracle 兼容模式冲突、完全无法在该模式下运行的 PG 专用扩展（例如 pg_partman 专为管理 PostgreSQL 分区表而设计，不支持在 Oracle 兼容模式下运行），需在适配文档和 PR 描述中说明情况。
+
+==== 组件编译安装
+
+请参考目标组件的官方文档进行编译安装。
+
+==== 测试 PG 模式
+
+启动 IvorySQL 实例，使用 psql 通过 5432 端口连接数据库，进行以下验证：
+
+. 扩展创建验证（仅适用于扩展类组件）：执行 `CREATE EXTENSION` 确认扩展可以正常创建，并确认版本与预期一致；
++
+[literal]
+----
+ivorysql=# CREATE EXTENSION <扩展名>;
+ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>';
+----
++
+[NOTE]
+通过 `shared_preload_libraries` 加载的钩子类组件无需此步骤，改为确认预加载后实例正常启动、组件行为生效。
+
+. 功能测试：根据组件文档提供的功能用例，逐一验证核心功能是否正常工作；
+. 回归测试：如果组件源码自带测试用例，应运行并确保其全部通过；
+. 边界测试：测试边界条件和异常场景，确认组件的健壮性。
+
+如果某个功能无法使用或测试失败，需排查原因：属于 IvorySQL 侧的问题，请向 IvorySQL 仓库提交 PR 修复；属于组件侧的问题，可向组件仓库反馈，并在适配文档中记录该限制。
+
+==== 测试 Oracle 兼容模式
+
+使用 psql 通过 1521 端口（Oracle 兼容端口）连接数据库，进行以下验证：
+
+. 参照 PG 模式的测试方法验证组件的主要功能；
+. 测试组件在 Oracle 兼容模式下的数据类型兼容性；
+. 测试组件功能是否支持 Oracle 风格的匿名块、存储过程、函数等。
+
+记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。
+
+测试时请注意以下两点：
+
+* *使用 Oracle 语法编写测试语句*。Oracle 兼容模式下的部分语法与 PG 模式不同，不能直接照搬 PG 模式的测试用例。例如：interval 类型需使用 Oracle 风格的语法，而非 PG 语法；`CREATE FUNCTION`、`CREATE PROCEDURE` 等语句需在末尾另起一行加 `/` 作为结束符。
+* *区分“输出差异”与“功能异常”*。部分输出与 PG 模式不一致属于正常现象，不应记为兼容性问题。例如：某些输出中的类型名会带有 `pg_catalog.` 模式前缀。判断功能是否正常，应以执行结果的语义是否正确为准，而不要求输出文本与 PG 模式逐字一致。
+
+记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。
+
+[NOTE]
+并非所有组件都能在 Oracle 兼容模式下工作。如果执行 `CREATE EXTENSION` 或调用组件功能时因语法错误而失败，多是组件内部使用了 Oracle 不支持的 PG 专用语法所致，请参考下一节的 PG 语法白名单机制进行修复；如果组件与 Oracle 兼容模式在底层机制上冲突（如 pg_partman），则需要在适配文档和 PR 描述中明确说明。
+
+==== 通过 PG 语法白名单修复兼容问题
+
+Oracle 兼容模式测试不通过——尤其是执行 `CREATE EXTENSION` 就直接失败——的一个常见原因是：扩展通过 SQL 脚本实现，脚本中大量使用了 Oracle 不支持的 PG 专用语法（如 PG 风格的 interval 表达式、数组切片等），导致脚本无法通过 Oracle 兼容模式下的语法解析。
+
+针对这种情况，IvorySQL 内核提供了 PG 语法白名单机制（见 `src/backend/commands/extension.c` 中的 `PgDialectExtensions` 列表）。扩展加入白名单后，在 Oracle 兼容模式集群中执行 `CREATE EXTENSION` 时：
+
+* 扩展的安装脚本会临时改用 PG 解析器解析执行，不受当前会话兼容模式的影响；
+* 安装脚本所创建的函数会被自动注入 `SET ivorysql.compatible_mode = pg` 配置，此后无论从哪种兼容模式的会话调用，函数体都由 PG 解析器解析执行。
+
+借助该机制，使用 PG 专用语法实现的扩展无需修改任何代码，即可在 Oracle 兼容模式集群中正常安装和运行。目前白名单中已包含 pg_profile、pg_repack 等扩展。
+
+该方式适用于：
+
+* 扩展主要通过 SQL 或 PL/pgSQL 实现，因使用 PG 专用语法导致 `CREATE EXTENSION` 或函数调用在 Oracle 兼容模式下失败；
+* 扩展功能自成一体（如统计信息采集、表重组等管理类扩展），用户只需调用其入口函数，不要求其内部实现与 Oracle 风格对象交互。
+
+该方式不适用于：
+
+* 扩展需要与用户创建的 Oracle 风格对象（存储过程、Oracle 专有数据类型等）深度交互，强制按 PG 语法解析会破坏这种交互；
+* 扩展与 Oracle 兼容模式在底层机制上冲突（如 pg_partman 依赖 PostgreSQL 原生的分区表管理），此类问题不在语法解析层面，白名单无法解决，仍需在适配文档和 PR 描述中说明限制。
+
+确认目标扩展属于适用场景后，您可以向 IvorySQL 仓库提交 PR，将扩展名加入 `PgDialectExtensions` 白名单，并在 PR 描述中附上两种模式下的测试结果；同时在适配文档的 "Oracle 兼容性" 章节中说明该扩展通过白名单机制运行。
+
+=== 第四步：文档编写
+
+IvorySQL 文档使用 AsciiDoc 编写的，其语法与 Markdown 类似但功能更加强大。如果不熟悉 AsciiDoc 语法，可参阅 xref:master/contribution/asciidoc_syntax_reference.adoc[asciidoc语法快速参考]。
+
+==== 文档结构
+
+每篇生态组件适配文档应包含以下章节（可根据组件特点适当调整）：
+
+[cols="1,3"]
+|===
+|章节 |说明
+
+|概述
+|介绍组件的功能、适用场景，以及与 IvorySQL 的关系
+
+|原理介绍
+|（可选）介绍组件的核心工作原理，帮助读者理解组件的运作机制
+
+|安装
+|详细的安装步骤，包括依赖安装、源码获取、编译安装、扩展创建等
+
+|配置
+|如果组件需要额外的配置步骤（如修改 `ivorysql.conf`、重启服务等），在此说明
+
+|使用
+|核心功能的使用示例，包括创建对象、执行操作、查询结果等
+
+|Oracle 兼容性
+|组件在 Oracle 兼容模式下的表现，包括支持的功能和已知限制
+|===
+
+==== 文档模板
+
+以下是一个生态组件适配文档的基础模板，贡献者可以在此基础上填充内容：
+
+[source,asciidoc]
+------
+:sectnums:
+:sectnumlevels: 5
+
+= <组件名称>
+
+== 概述
+<组件功能介绍、适用场景、与 IvorySQL 的关系>
+
+项目地址：<https://github.com/xxx/xxx>
+
+版本：<适配的组件版本号>
+
+开源协议：<组件的开源协议>
+
+== 安装
+
+[TIP]
+源码测试安装环境为 <操作系统版本>，环境中已安装 IvorySQL 5 及以上版本，安装路径为 /usr/local/ivorysql/ivorysql-5
+
+=== 依赖
+<列出并说明安装所需的依赖>
+
+=== 源码安装
+[literal]
+----
+# 获取源码
+git clone <仓库地址>
+cd <目录>
+
+# 设置 pg_config 路径
+export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config
+
+# 编译安装
+make
+sudo make install
+----
+
+=== 创建扩展
+[literal]
+----
+ivorysql=# CREATE EXTENSION <扩展名>;
+CREATE EXTENSION
+
+ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>';
+----
+
+== 使用
+
+=== <功能点一>
+<使用示例及输出>
+
+=== <功能点二>
+<使用示例及输出>
+
+== Oracle 兼容性
+<可选：在 Oracle 兼容模式下的测试结果>
+------
+
+==== 同步更新概述页
+
+完成组件文档编写后，请务必同步更新 xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc] 中的插件列表表格，在表格末尾追加一行新记录，包含以下信息：
+
+* 序号：当前最大序号加 1
+* 插件名称：带 xref 链接的插件名称
+* 版本：您适配的组件版本
+* 功能描述：一句话概括组件功能
+* 适用场景：列举主要适用场景
+
+[NOTE]
+中英文版本的概述页都需要同步更新。
+
+=== 第五步：提交 PR
+
+==== 创建分支
+
+生态组件适配文档统一提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库（注意：不是创建 Issue 的 IvorySQL 主仓库）。请先 fork 该仓库并 clone 到本地，然后创建特性分支：
+
+[literal]
+----
+git checkout -b feature/adapt-<组件名称>
+----
+
+==== 添加文件
+
+. 将文档文件放入 `CN/modules/ROOT/pages/master/ecosystem_components/` 目录
+. 如有图片资源，放入 `CN/modules/ROOT/images/` 目录
+. 同步准备英文版本，放入对应的 EN 目录
+. 更新 CN 和 EN 的 `nav.adoc` 和 `ecosystem_overview.adoc` 里的链接
+
+==== 创建 PR
+
+. 向 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库的 master 分支提交 PR
+. 在 PR 描述中使用 `Fixes IvorySQL/IvorySQL#<编号>` 关联第一步中认领或新建的适配 Issue
+. 在 PR 描述中说明：
+* 适配的组件名称和版本
+* 测试环境信息
+* 已完成的测试项目
+* 已知的限制或问题
+
+[NOTE]
+====
+. 由于 Issue 位于 IvorySQL 主仓库，必须使用 `IvorySQL/IvorySQL#编号` 的完整引用格式；PR 合并后，对应 Issue 会被自动关闭。
+. 关联关键字必须写在 IvorySQL docs 仓库提交的 PR 描述中且拼写规范（`Fixes`/`Closes`/`Resolves` + 空格 + `IvorySQL/IvorySQL#<编号>`），写在评论里无效。
+====
+
+==== 等待评审
+
+维护者会按照文档中的步骤复现测试，并对 PR 进行评审，可能会提出以下修改建议：
+
+* 补充缺失的测试用例
+* 修正文档格式问题
+* 完善 Oracle 兼容性测试
+* 补充英文版翻译
+
+请根据评审意见及时修改并更新 PR。
+
+== 常见问题
+
+=== 编译报错找不到 pg_config
+
+请确认 `PG_CONFIG` 环境变量设置正确，指向 IvorySQL 安装目录下的 `bin/pg_config`。可以通过以下命令确认：
+
+[literal]
+----
+$PG_CONFIG --version
+----
+
+=== 扩展创建失败
+
+请检查：
+
+. 扩展的 `.so` 文件是否正确安装到 IvorySQL 的 `lib` 目录
+. 扩展的 `.sql` 和 `.control` 文件是否正确安装到 `share/extension` 目录
+. IvorySQL 版本是否与组件要求的 PostgreSQL 版本兼容
+. 若失败原因是 PG 专用语法无法解析，可参考第三步的 PG 语法白名单机制。
+
+=== Oracle 兼容模式下功能异常
+
+部分 PostgreSQL 扩展依赖 PG 原生解析器，在 Oracle 兼容模式下可能无法正常工作。遇到此类问题时，请在文档的 "Oracle 兼容性" 章节中明确说明限制，并提供替代方案（如有）。
+
+=== 不确定组件是否适合适配
+
+请先在 https://github.com/IvorySQL/IvorySQL/issues[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。
+

EN/modules/ROOT/nav.adoc

@@ -79,6 +79,7 @@
 * IvorySQL Developers
 ** xref:master/developer_guide.adoc[Developer]
 ** xref:master/contribution/community_contribution_guide.adoc[Community contribution]
+** xref:master/contribution/ecosystem_contribution_guide.adoc[Ecosystem Contribution Guide]
 * IvorySQL Architecture Design
 ** Query Processing
 *** xref:master/architecture/dual_parser.adoc[Dual Parser]