From 4e5165d466adcf9f73dde028c667e80c57a48a51 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Wed, 8 Jul 2026 15:23:50 +0800 Subject: [PATCH 01/10] docs: add ecosystem component adaptation contribution guide - Add Chinese and English ecosystem component adaptation contribution guides (ecosystem_contribution_guide.adoc) - Place under IvorySQL Developers > contribution directory - Update Chinese and English nav.adoc to add navigation entries --- CN/modules/ROOT/nav.adoc | 1 + .../ecosystem_contribution_guide.adoc | 313 ++++++++++++++++++ EN/modules/ROOT/nav.adoc | 1 + .../ecosystem_contribution_guide.adoc | 313 ++++++++++++++++++ 4 files changed, 628 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc create mode 100644 EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 991c4af..b5f0e10 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -81,6 +81,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架构设计 *** 查询处理 diff --git a/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc new file mode 100644 index 0000000..ba7c06a --- /dev/null +++ b/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc @@ -0,0 +1,313 @@ +:sectnums: +:sectnumlevels: 5 + += 生态组件适配贡献指南 + +== 概述 + +IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 + +本文档旨在为有意参与生态组件适配的贡献者提供完整的指引，涵盖从选题、环境准备、适配测试、文档编写到提交贡献的全流程。 + +== 适配范围 + +=== 适合的组件类型 + +以下类型的组件欢迎贡献者进行适配： + +* PostgreSQL 社区官方扩展（contrib 模块或知名第三方扩展） +* 基于 PostgreSQL 扩展机制开发的工具类插件 +* 与数据库运维、监控、性能分析相关的工具 +* 数据迁移、同步、备份相关的工具 +* 全文检索、向量检索、图数据库等增强型扩展 +* 连接池、代理、中间件等周边生态工具 + +=== 不适合的组件 + +* 依赖特定操作系统或硬件架构且无法在主流平台运行的组件 +* 与 IvorySQL Oracle 兼容模式存在根本性冲突且无法解决的组件 +* 已停止维护或存在严重安全问题的组件 +* 商业闭源且无法提供社区测试版本的组件 + +== 贡献流程 + +=== 第一步：选题与沟通 + +==== 查找已有适配 + +在开始适配工作之前，请先查阅 xref:master/ecosystem_components/ecosystem_overview.adoc[生态插件适配列表]，确认目标组件是否已完成适配。 + +==== 提交 Issue + +如果您希望适配一个尚未收录的组件，请首先在 https://github.com/IvorySQL/ivorysql_docs[ivorysql_docs 仓库] 提交一个 Issue，说明以下内容： + +* 组件名称及项目地址 +* 组件功能描述及适用场景 +* 组件的开源协议 +* 组件最近的维护状态（是否活跃维护） +* 您计划适配的组件版本 + +维护者会评估该组件是否适合纳入 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_CONFIG` 环境变量指向 IvorySQL 的 `pg_config` ++ +[literal] +---- +export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config +---- + +. 按照组件官方文档进行编译安装 ++ +[literal] +---- +# 以某扩展为例 +git clone <组件源码仓库地址> +cd <组件目录> +make +sudo make install +---- + +==== 功能验证 + +编译安装成功后，需要进行以下验证： + +. *扩展创建验证*：在 IvorySQL 中执行 `CREATE EXTENSION` 创建扩展，确认扩展可以正常加载 ++ +[literal] +---- +ivorysql=# CREATE EXTENSION <扩展名>; +CREATE EXTENSION +---- + +. *版本确认*：确认安装的扩展版本与预期一致 ++ +[literal] +---- +ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; +---- + +. *功能测试*：根据组件文档提供的功能用例，逐一验证核心功能是否正常工作 +. *边界测试*：测试一些边界条件和异常场景，确认扩展的健壮性 + +==== Oracle 兼容性测试 + +如果目标组件需要在 IvorySQL 的 Oracle 兼容模式下使用，还需要进行额外的兼容性测试： + +. 使用 1521 端口（Oracle 兼容模式默认端口）连接数据库 ++ +[literal] +---- +psql -p 1521 +---- + +. 测试组件在 Oracle 兼容模式下的数据类型兼容性 +. 测试组件功能是否支持 Oracle 风格的匿名块、存储过程、函数等 +. 记录所有兼容性问题及解决方案 + +[NOTE] +并非所有组件都支持 Oracle 兼容模式。如果组件依赖 PostgreSQL 特有的内部机制（如使用 `pg_query` 模块进行语句解析），可能无法在 Oracle 兼容模式下运行，需要在文档中明确说明。 + +=== 第四步：文档编写 + +==== 文档结构 + +每篇生态组件适配文档应包含以下章节（可根据组件特点适当调整）： + +[cols="1,3"] +|=== +|章节 |说明 + +|概述 +|介绍组件的功能、适用场景，以及与 IvorySQL 的关系 + +|原理介绍 +|（可选）介绍组件的核心工作原理，帮助读者理解组件的运作机制 + +|安装 +|详细的安装步骤，包括依赖安装、源码获取、编译安装、扩展创建等 + +|配置 +|（可选）如果组件需要额外的配置步骤（如修改 `ivorysql.conf`、重启服务等），在此说明 + +|使用 +|核心功能的使用示例，包括创建对象、执行操作、查询结果等 + +|Oracle 兼容性 +|（可选）组件在 Oracle 兼容模式下的表现，包括支持的功能和已知限制 +|=== + +==== 文档模板 + +以下是一个生态组件适配文档的基础模板，贡献者可以在此基础上填充内容： + +[source,asciidoc] +------ +:sectnums: +:sectnumlevels: 5 + += <组件名称> + +== 概述 +<组件功能介绍、适用场景、与 IvorySQL 的关系> + +项目地址： + +版本：<适配的组件版本号> + +开源协议：<组件的开源协议> + +== 安装 + +[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 + +==== 创建分支 + +在您的 fork 仓库中创建特性分支： + +[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 + +. 在 PR 标题或描述中关联对应的 Issue 编号（如 `Fixes #123`） +. 在 PR 描述中说明： +* 适配的组件名称和版本 +* 测试环境信息 +* 已完成的测试项目 +* 已知的限制或问题 + +==== 等待评审 + +维护者会对 PR 进行评审，可能会提出以下修改建议： + +* 补充缺失的测试用例 +* 修正文档格式问题 +* 完善 Oracle 兼容性测试 +* 补充英文版翻译 + +请根据评审意见及时修改并更新 PR。 + +== 常见问题 + +=== 编译报错找不到 pg_config + +请确认 `PG_CONFIG` 环境变量设置正确，指向 IvorySQL 安装目录下的 `bin/pg_config`。可以通过以下命令确认： + +[literal] +---- +$PG_CONFIG --version +---- + +=== 扩展创建失败 + +请检查： + +. 扩展的 `.so` 文件是否正确安装到 IvorySQL 的 `lib` 目录 +. 扩展的 `.sql` 和 `.control` 文件是否正确安装到 `share/extension` 目录 +. IvorySQL 版本是否与组件要求的 PostgreSQL 版本兼容 + +=== Oracle 兼容模式下功能异常 + +部分 PostgreSQL 扩展依赖 PG 原生解析器，在 Oracle 兼容模式下可能无法正常工作。遇到此类问题时，请在文档的 "Oracle 兼容性" 章节中明确说明限制，并提供替代方案（如有）。 + +=== 不确定组件是否适合适配 + +请先在 https://github.com/IvorySQL/ivorysql_docs[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。 diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index b071b69..38f0ef3 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -82,6 +82,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] diff --git a/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc new file mode 100644 index 0000000..bdb8cea --- /dev/null +++ b/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc @@ -0,0 +1,313 @@ +:sectnums: +:sectnumlevels: 5 + += Ecosystem Component Adaptation Contribution Guide + +== Overview + +As an Oracle-compatible database built on PostgreSQL, IvorySQL naturally inherits PostgreSQL's rich extension ecosystem. To enable more PostgreSQL ecosystem components to run stably on IvorySQL, the IvorySQL community welcomes external contributors to participate in ecosystem component adaptation work. + +This document provides complete guidance for contributors who want to participate in ecosystem component adaptation, covering the entire process from topic selection, environment preparation, adaptation testing, documentation writing, to contribution submission. + +== Adaptation Scope + +=== Suitable Component Types + +The following types of components are welcome for adaptation contributions: + +* Official PostgreSQL community extensions (contrib modules or well-known third-party extensions) +* Utility plugins developed based on PostgreSQL's extension mechanism +* Tools related to database operations, monitoring, and performance analysis +* Tools related to data migration, synchronization, and backup +* Enhanced extensions such as full-text search, vector search, and graph databases +* Peripheral ecosystem tools such as connection pools, proxies, and middleware + +=== Unsuitable Components + +* Components that depend on specific operating systems or hardware architectures and cannot run on mainstream platforms +* Components that have fundamental conflicts with IvorySQL's Oracle compatibility mode and cannot be resolved +* Components that are no longer maintained or have serious security issues +* Commercial closed-source components that cannot provide community test versions + +== Contribution Process + +=== Step 1: Topic Selection and Communication + +==== Check Existing Adaptations + +Before starting adaptation work, please check the xref:master/ecosystem_components/ecosystem_overview.adoc[Ecosystem Plugin Compatibility List] to confirm whether the target component has already been adapted. + +==== Submit an Issue + +If you want to adapt a component not yet included, please first submit an Issue on the https://github.com/IvorySQL/ivorysql_docs[ivorysql_docs repository], including the following information: + +* Component name and project URL +* Component description and use cases +* Component's open-source license +* Recent maintenance status (whether actively maintained) +* The component version you plan to adapt + +Maintainers will evaluate whether the component is suitable for inclusion in the IvorySQL ecosystem and communicate with you through the Issue. + +[TIP] +It is recommended to start adaptation work only after receiving confirmation from maintainers to avoid unnecessary effort. + +==== Sign the CLA + +Before submitting documentation contributions, please ensure you have signed the Contributor License Agreement (CLA). For details, please refer to the CLA signing instructions in the xref:master/contribution/community_contribution_guide.adoc[Community Contribution Guide]. + +=== Step 2: Environment Preparation + +==== IvorySQL Environment + +Please prepare an IvorySQL environment for testing, preferably meeting the following requirements: + +* IvorySQL version: 5.0 or above +* Operating system: Ubuntu 24.04 (x86_64) or other mainstream Linux distributions recommended +* Installation path: Note the IvorySQL installation path, as the `pg_config` path will be needed when compiling extensions later + +[TIP] +You can quickly set up a test environment using IvorySQL's official Docker images. Refer to xref:master/containerization/docker_podman_deployment.adoc[Docker & Podman Deployment]. + +==== Build Toolchain + +Prepare the appropriate toolchain based on the target component's build method: + +* C/C++ extensions: gcc, make, and other basic build tools +* Rust extensions: cargo, rustc, and other Rust toolchain components +* Extensions in other languages: corresponding language runtime environments + +=== Step 3: Adaptation Testing + +==== Source Compilation + +Obtain the source code from the component's official repository and compile it following these steps: + +. Set the `PG_CONFIG` environment variable to point to IvorySQL's `pg_config` ++ +[literal] +---- +export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config +---- + +. Compile and install according to the component's official documentation ++ +[literal] +---- +# Taking an extension as an example +git clone +cd +make +sudo make install +---- + +==== Functionality Verification + +After successful compilation and installation, perform the following verifications: + +. *Extension creation verification*: Execute `CREATE EXTENSION` in IvorySQL to create the extension and confirm it loads correctly ++ +[literal] +---- +ivorysql=# CREATE EXTENSION ; +CREATE EXTENSION +---- + +. *Version confirmation*: Confirm the installed extension version matches expectations ++ +[literal] +---- +ivorysql=# SELECT * FROM pg_available_extensions WHERE name = ''; +---- + +. *Functionality testing*: Verify core functionality works correctly by following the test cases provided in the component documentation +. *Boundary testing*: Test boundary conditions and exception scenarios to confirm the extension's robustness + +==== Oracle Compatibility Testing + +If the target component needs to be used in IvorySQL's Oracle compatibility mode, additional compatibility testing is required: + +. Connect to the database using port 1521 (the default port for Oracle compatibility mode) ++ +[literal] +---- +psql -p 1521 +---- + +. Test data type compatibility in Oracle compatibility mode +. Test whether component functionality supports Oracle-style anonymous blocks, stored procedures, functions, etc. +. Document all compatibility issues and solutions + +[NOTE] +Not all components support Oracle compatibility mode. If a component relies on PostgreSQL-specific internal mechanisms (such as using the `pg_query` module for statement parsing), it may not work in Oracle compatibility mode. This must be clearly stated in the documentation. + +=== Step 4: Documentation Writing + +==== Document Structure + +Each ecosystem component adaptation document should include the following sections (adjust as appropriate based on component characteristics): + +[cols="1,3"] +|=== +|Section |Description + +|Overview +|Introduce the component's functionality, use cases, and relationship with IvorySQL + +|Principle Introduction +|(Optional) Explain the component's core working principles to help readers understand how it works + +|Installation +|Detailed installation steps, including dependency installation, source acquisition, compilation, extension creation, etc. + +|Configuration +|(Optional) If the component requires additional configuration steps (such as modifying `ivorysql.conf`, restarting services, etc.), explain them here + +|Usage +|Usage examples for core functionality, including object creation, operation execution, query results, etc. + +|Oracle Compatibility +|(Optional) Component behavior in Oracle compatibility mode, including supported features and known limitations +|=== + +==== Document Template + +Below is a basic template for ecosystem component adaptation documentation. Contributors can fill in content based on this template: + +[source,asciidoc] +------ +:sectnums: +:sectnumlevels: 5 + += + +== Overview + + +Project URL: + +Version: + +License: + +== Installation + +[TIP] +Source test installation environment is , with IvorySQL 5+ already installed at /usr/local/ivorysql/ivorysql-5 + +=== Dependencies + + +=== Source Installation +[literal] +---- +# Get source code +git clone +cd + +# Set pg_config path +export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config + +# Compile and install +make +sudo make install +---- + +=== Create Extension +[literal] +---- +ivorysql=# CREATE EXTENSION ; +CREATE EXTENSION + +ivorysql=# SELECT * FROM pg_available_extensions WHERE name = ''; +---- + +== Usage + +=== + + +=== + + +== Oracle Compatibility + +------ + +==== Update the Overview Page + +After completing the component documentation, please make sure to update the plugin list table in xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc] by appending a new row at the end of the table with the following information: + +* Index: Current maximum index + 1 +* Plugin name: Plugin name with xref link +* Version: The component version you adapted +* Function description: One-sentence summary of component functionality +* Use cases: List main use cases + +[NOTE] +Both the Chinese and English versions of the overview page need to be updated. + +=== Step 5: Submit PR + +==== Create Branch + +Create a feature branch in your forked repository: + +[literal] +---- +git checkout -b feature/adapt- +---- + +==== Add Files + +. Place the documentation file in the `CN/modules/ROOT/pages/master/ecosystem_components/` directory +. If there are image resources, place them in the `CN/modules/ROOT/images/` directory +. Prepare the English version simultaneously and place it in the corresponding EN directory +. Update both CN and EN `nav.adoc` and `ecosystem_overview.adoc` + +==== Submit PR + +. Link the corresponding Issue number in the PR title or description (e.g., `Fixes #123`) +. In the PR description, explain: +* The adapted component name and version +* Test environment information +* Completed test items +* Known limitations or issues + +==== Await Review + +Maintainers will review the PR and may suggest the following modifications: + +* Add missing test cases +* Fix documentation format issues +* Improve Oracle compatibility testing +* Add English translation + +Please revise and update the PR promptly based on review feedback. + +== Frequently Asked Questions + +=== Compilation Error: Cannot Find pg_config + +Please confirm the `PG_CONFIG` environment variable is set correctly, pointing to `bin/pg_config` under the IvorySQL installation directory. You can verify with: + +[literal] +---- +$PG_CONFIG --version +---- + +=== Extension Creation Fails + +Please check: + +. Whether the extension's `.so` file is correctly installed in IvorySQL's `lib` directory +. Whether the extension's `.sql` and `.control` files are correctly installed in the `share/extension` directory +. Whether the IvorySQL version is compatible with the PostgreSQL version required by the component + +=== Functionality Issues in Oracle Compatibility Mode + +Some PostgreSQL extensions rely on the native PG parser and may not work correctly in Oracle compatibility mode. When encountering such issues, clearly state the limitations in the document's "Oracle Compatibility" section and provide alternative solutions if available. + +=== Unsure Whether a Component Is Suitable for Adaptation + +Please start a discussion in https://github.com/IvorySQL/ivorysql_docs[Issues], describing the component's functionality and your adaptation plan. Maintainers will provide an assessment. From 2e7c82a3dd48e807d7c90b43533b6002e7fce16f Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Thu, 16 Jul 2026 15:47:13 +0800 Subject: [PATCH 02/10] docs: update ecosystem contribution guide --- .../ecosystem_contribution_guide.adoc | 159 ++++++++++-------- .../ecosystem_contribution_guide.adoc | 159 +++++++++--------- 2 files changed, 169 insertions(+), 149 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc index ba7c06a..6234786 100644 --- a/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc @@ -11,46 +11,35 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 == 适配范围 -=== 适合的组件类型 - 以下类型的组件欢迎贡献者进行适配： -* PostgreSQL 社区官方扩展（contrib 模块或知名第三方扩展） -* 基于 PostgreSQL 扩展机制开发的工具类插件 -* 与数据库运维、监控、性能分析相关的工具 -* 数据迁移、同步、备份相关的工具 -* 全文检索、向量检索、图数据库等增强型扩展 -* 连接池、代理、中间件等周边生态工具 +* PostgreSQL 社区官方扩展（contrib 模块） +* 基于 PostgreSQL 扩展机制开发的第三方插件 +* 以独立进程形式与数据库配合工作的周边生态工具，如连接池、代理、中间件等 -=== 不适合的组件 +== 贡献流程 -* 依赖特定操作系统或硬件架构且无法在主流平台运行的组件 -* 与 IvorySQL Oracle 兼容模式存在根本性冲突且无法解决的组件 -* 已停止维护或存在严重安全问题的组件 -* 商业闭源且无法提供社区测试版本的组件 +生态组件适配，是将 PostgreSQL 生态组件适配到 IvorySQL 的工作。主要内容包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档，提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库。文档提交后，维护者会按照适配文档中给出的步骤对目标组件进行复现测试，确认测试结果与文档描述一致后，合并该 PR。 -== 贡献流程 +具体的选题、测试、文档编写等环节，请参考下面的详细步骤。 === 第一步：选题与沟通 -==== 查找已有适配 +==== 确认组件未被适配 -在开始适配工作之前，请先查阅 xref:master/ecosystem_components/ecosystem_overview.adoc[生态插件适配列表]，确认目标组件是否已完成适配。 +在开始适配工作之前，请先查阅 xref:master/ecosystem_components/ecosystem_overview.adoc[生态组件适配列表]，确认目标组件是否已完成适配。如果目标组件不在列表中，则继续后面的流程；否则，请重新选择一个未适配的组件。 -==== 提交 Issue +==== 认领或新建 Issue -如果您希望适配一个尚未收录的组件，请首先在 https://github.com/IvorySQL/ivorysql_docs[ivorysql_docs 仓库] 提交一个 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 获得维护者确认后再开始适配工作，避免无效劳动。 +建议在 Issue 获得维护者确认后再开始适配工作，避免重复或无效工作。 ==== 签署 CLA @@ -79,70 +68,83 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 === 第三步：适配测试 -==== 源码编译 +生态组件适配的目标分为两个层面： -从组件的官方仓库获取源码，按照以下步骤进行编译： +- PG 模式：组件必须完全可用。 +- Oracle 兼容模式：应尽可能做到完全可用；若无法完全可用，至少应保证主要功能可以正常运行。对于底层机制与 Oracle 兼容模式冲突、完全无法在该模式下运行的 PG 专用扩展（例如 pg_partman 专为管理 PostgreSQL 分区表而设计，不支持在 Oracle 兼容模式下运行），需在适配文档和 PR 描述中说明情况。 -. 设置 `PG_CONFIG` 环境变量指向 IvorySQL 的 `pg_config` -+ -[literal] ----- -export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config ----- +==== 组件编译安装 -. 按照组件官方文档进行编译安装 -+ -[literal] ----- -# 以某扩展为例 -git clone <组件源码仓库地址> -cd <组件目录> -make -sudo make install ----- +请参考目标组件的官方文档进行编译安装。 -==== 功能验证 +==== 测试 PG 模式 -编译安装成功后，需要进行以下验证： +启动 IvorySQL 实例，使用 psql 通过 5432 端口连接数据库，进行以下验证： -. *扩展创建验证*：在 IvorySQL 中执行 `CREATE EXTENSION` 创建扩展，确认扩展可以正常加载 +. 扩展创建验证（仅适用于扩展类组件）：执行 `CREATE EXTENSION` 确认扩展可以正常创建，并确认版本与预期一致； + [literal] ---- ivorysql=# CREATE EXTENSION <扩展名>; -CREATE EXTENSION ----- - -. *版本确认*：确认安装的扩展版本与预期一致 -+ -[literal] ----- ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; ---- ++ +[NOTE] +通过 `shared_preload_libraries` 加载的钩子类组件无需此步骤，改为确认预加载后实例正常启动、组件行为生效。 -. *功能测试*：根据组件文档提供的功能用例，逐一验证核心功能是否正常工作 -. *边界测试*：测试一些边界条件和异常场景，确认扩展的健壮性 +. 功能测试：根据组件文档提供的功能用例，逐一验证核心功能是否正常工作； +. 回归测试：如果组件源码自带测试用例，应运行并确保其全部通过； +. 边界测试：测试边界条件和异常场景，确认组件的健壮性。 -==== Oracle 兼容性测试 +如果某个功能无法使用或测试失败，需排查原因：属于 IvorySQL 侧的问题，请向 IvorySQL 仓库提交 PR 修复；属于组件侧的问题，可向组件仓库反馈，并在适配文档中记录该限制。 -如果目标组件需要在 IvorySQL 的 Oracle 兼容模式下使用，还需要进行额外的兼容性测试： +==== 测试 Oracle 兼容模式 -. 使用 1521 端口（Oracle 兼容模式默认端口）连接数据库 -+ -[literal] ----- -psql -p 1521 ----- +使用 psql 通过 1521 端口（Oracle 兼容端口）连接数据库，进行以下验证： + +. 参照 PG 模式的测试方法验证组件的主要功能； +. 测试组件在 Oracle 兼容模式下的数据类型兼容性； +. 测试组件功能是否支持 Oracle 风格的匿名块、存储过程、函数等。 + +记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。 -. 测试组件在 Oracle 兼容模式下的数据类型兼容性 -. 测试组件功能是否支持 Oracle 风格的匿名块、存储过程、函数等 -. 记录所有兼容性问题及解决方案 +测试时请注意以下两点： + +* *使用 Oracle 语法编写测试语句*。Oracle 兼容模式下的部分语法与 PG 模式不同，不能直接照搬 PG 模式的测试用例。例如：interval 类型需使用 Oracle 风格的语法，而非 PG 语法；`CREATE FUNCTION`、`CREATE PROCEDURE` 等语句需在末尾另起一行加 `/` 作为结束符。 +* *区分“输出差异”与“功能异常”*。部分输出与 PG 模式不一致属于正常现象，不应记为兼容性问题。例如：某些输出中的类型名会带有 `pg_catalog.` 模式前缀。判断功能是否正常，应以执行结果的语义是否正确为准，而不要求输出文本与 PG 模式逐字一致。 + +记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。 [NOTE] -并非所有组件都支持 Oracle 兼容模式。如果组件依赖 PostgreSQL 特有的内部机制（如使用 `pg_query` 模块进行语句解析），可能无法在 Oracle 兼容模式下运行，需要在文档中明确说明。 +并非所有组件都能在 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语法快速参考]。 + ==== 文档结构 每篇生态组件适配文档应包含以下章节（可根据组件特点适当调整）： @@ -161,13 +163,13 @@ psql -p 1521 |详细的安装步骤，包括依赖安装、源码获取、编译安装、扩展创建等 |配置 -|（可选）如果组件需要额外的配置步骤（如修改 `ivorysql.conf`、重启服务等），在此说明 +|如果组件需要额外的配置步骤（如修改 `ivorysql.conf`、重启服务等），在此说明 |使用 |核心功能的使用示例，包括创建对象、执行操作、查询结果等 |Oracle 兼容性 -|（可选）组件在 Oracle 兼容模式下的表现，包括支持的功能和已知限制 +|组件在 Oracle 兼容模式下的表现，包括支持的功能和已知限制 |=== ==== 文档模板 @@ -251,7 +253,7 @@ ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; ==== 创建分支 -在您的 fork 仓库中创建特性分支： +生态组件适配文档统一提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库（注意：不是创建 Issue 的 IvorySQL 主仓库）。请先 fork 该仓库并 clone 到本地，然后创建特性分支： [literal] ---- @@ -263,20 +265,27 @@ git checkout -b feature/adapt-<组件名称> . 将文档文件放入 `CN/modules/ROOT/pages/master/ecosystem_components/` 目录 . 如有图片资源，放入 `CN/modules/ROOT/images/` 目录 . 同步准备英文版本，放入对应的 EN 目录 -. 更新 CN 和 EN 的 `nav.adoc` 和 `ecosystem_overview.adoc` +. 更新 CN 和 EN 的 `nav.adoc` 和 `ecosystem_overview.adoc` 里的链接 -==== 提交 PR +==== 创建 PR -. 在 PR 标题或描述中关联对应的 Issue 编号（如 `Fixes #123`） +. 向 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 进行评审，可能会提出以下修改建议： +维护者会按照文档中的步骤复现测试，并对 PR 进行评审，可能会提出以下修改建议： * 补充缺失的测试用例 * 修正文档格式问题 @@ -303,6 +312,7 @@ $PG_CONFIG --version . 扩展的 `.so` 文件是否正确安装到 IvorySQL 的 `lib` 目录 . 扩展的 `.sql` 和 `.control` 文件是否正确安装到 `share/extension` 目录 . IvorySQL 版本是否与组件要求的 PostgreSQL 版本兼容 +. 若失败原因是 PG 专用语法无法解析，可参考第三步的 PG 语法白名单机制。 === Oracle 兼容模式下功能异常 @@ -310,4 +320,5 @@ $PG_CONFIG --version === 不确定组件是否适合适配 -请先在 https://github.com/IvorySQL/ivorysql_docs[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。 +请先在 https://github.com/IvorySQL/IvorySQL/issues[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。 + diff --git a/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc index bdb8cea..9ea4d2d 100644 --- a/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc +++ b/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc @@ -11,46 +11,35 @@ This document provides complete guidance for contributors who want to participat == Adaptation Scope -=== Suitable Component Types - The following types of components are welcome for adaptation contributions: -* Official PostgreSQL community extensions (contrib modules or well-known third-party extensions) -* Utility plugins developed based on PostgreSQL's extension mechanism -* Tools related to database operations, monitoring, and performance analysis -* Tools related to data migration, synchronization, and backup -* Enhanced extensions such as full-text search, vector search, and graph databases -* Peripheral ecosystem tools such as connection pools, proxies, and middleware +* Official PostgreSQL community extensions (contrib modules) +* Third-party plugins developed based on PostgreSQL's extension mechanism +* Peripheral ecosystem tools that work alongside the database as independent processes, such as connection pools, proxies, and middleware -=== Unsuitable Components +== Contribution Process -* Components that depend on specific operating systems or hardware architectures and cannot run on mainstream platforms -* Components that have fundamental conflicts with IvorySQL's Oracle compatibility mode and cannot be resolved -* Components that are no longer maintained or have serious security issues -* Commercial closed-source components that cannot provide community test versions +Ecosystem component adaptation is the work of adapting PostgreSQL ecosystem components to run on IvorySQL. The main activities include: understanding the target component's characteristics, principles, and usage; testing whether it works correctly under IvorySQL's PG mode and Oracle compatibility mode; and finally, based on the above research and testing, writing an ecosystem component adaptation document and submitting it to the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository. After the document is submitted, maintainers will reproduce the test of the target component following the steps given in the adaptation document; once they confirm the test results are consistent with the document, they will merge the PR. -== Contribution Process +For the specific steps of topic selection, testing, and documentation writing, please refer to the detailed steps below. === Step 1: Topic Selection and Communication -==== Check Existing Adaptations +==== Confirm the Component Is Not Yet Adapted -Before starting adaptation work, please check the xref:master/ecosystem_components/ecosystem_overview.adoc[Ecosystem Plugin Compatibility List] to confirm whether the target component has already been adapted. +Before starting adaptation work, please check the xref:master/ecosystem_components/ecosystem_overview.adoc[Ecosystem Component Adaptation List] to confirm whether the target component has already been adapted. If the target component is not in the list, continue with the following process; otherwise, please choose another unadapted component. -==== Submit an Issue +==== Claim or Create an Issue -If you want to adapt a component not yet included, please first submit an Issue on the https://github.com/IvorySQL/ivorysql_docs[ivorysql_docs repository], including the following information: +Search for the target component in the https://github.com/IvorySQL/IvorySQL/issues[Issue list] of the IvorySQL repository: -* Component name and project URL -* Component description and use cases -* Component's open-source license -* Recent maintenance status (whether actively maintained) -* The component version you plan to adapt +- If a related adaptation Issue already exists, first confirm it has not yet been assigned (the Assignees field is empty), then click `Assign yourself` in the Assignees area in the upper-right corner to claim the Issue; if it has already been claimed by someone else, please choose another component. +- If no related Issue exists yet, create a new `Feature Request` Issue, add the `compatibility` label, and assign it to yourself. You can refer to existing ecosystem component adaptation Issues for the format: the title should follow the pattern `Ecosystem Integration: `, and the body should describe the component to be adapted and its use in one sentence. Maintainers will evaluate whether the component is suitable for inclusion in the IvorySQL ecosystem and communicate with you through the Issue. [TIP] -It is recommended to start adaptation work only after receiving confirmation from maintainers to avoid unnecessary effort. +It is recommended to start adaptation work only after receiving confirmation from maintainers to avoid duplicate or unnecessary work. ==== Sign the CLA @@ -79,67 +68,78 @@ Prepare the appropriate toolchain based on the target component's build method: === Step 3: Adaptation Testing -==== Source Compilation +The goals of ecosystem component adaptation are divided into two levels: -Obtain the source code from the component's official repository and compile it following these steps: +- PG mode: the component must be fully usable. +- Oracle compatibility mode: it should be fully usable if possible; if it cannot be fully usable, at least the core functionality should work normally. For PG-specific extensions whose underlying mechanisms fundamentally conflict with Oracle compatibility mode and cannot run in this mode at all (for example, pg_partman, which is designed specifically to manage PostgreSQL partitioned tables and does not support running in Oracle compatibility mode), you must explain the situation in the adaptation document and the PR description. -. Set the `PG_CONFIG` environment variable to point to IvorySQL's `pg_config` -+ -[literal] ----- -export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config ----- +==== Compile and Install the Component -. Compile and install according to the component's official documentation -+ -[literal] ----- -# Taking an extension as an example -git clone -cd -make -sudo make install ----- +Please refer to the target component's official documentation for compilation and installation. -==== Functionality Verification +==== Test PG Mode -After successful compilation and installation, perform the following verifications: +Start an IvorySQL instance, connect to the database with psql through port 5432, and perform the following verifications: -. *Extension creation verification*: Execute `CREATE EXTENSION` in IvorySQL to create the extension and confirm it loads correctly +. Extension creation verification (only for extension-type components): run `CREATE EXTENSION` to confirm the extension can be created normally, and confirm the version matches expectations; + [literal] ---- ivorysql=# CREATE EXTENSION ; -CREATE EXTENSION ----- - -. *Version confirmation*: Confirm the installed extension version matches expectations -+ -[literal] ----- ivorysql=# SELECT * FROM pg_available_extensions WHERE name = ''; ---- ++ +[NOTE] +Hook-type components loaded via `shared_preload_libraries` do not need this step; instead, confirm that after preloading the instance starts normally and the component's behavior takes effect. -. *Functionality testing*: Verify core functionality works correctly by following the test cases provided in the component documentation -. *Boundary testing*: Test boundary conditions and exception scenarios to confirm the extension's robustness +. Functionality testing: verify the core functionality item by item according to the test cases provided in the component documentation; +. Regression testing: if the component's source code ships with its own test cases, run them and ensure they all pass; +. Boundary testing: test boundary conditions and exception scenarios to confirm the component's robustness. -==== Oracle Compatibility Testing +If a certain function cannot be used or a test fails, investigate the cause: if it is an IvorySQL-side issue, open a PR against the IvorySQL repository to fix it; if it is a component-side issue, report it to the component's repository and record the limitation in the adaptation document. -If the target component needs to be used in IvorySQL's Oracle compatibility mode, additional compatibility testing is required: +==== Test Oracle Compatibility Mode -. Connect to the database using port 1521 (the default port for Oracle compatibility mode) -+ -[literal] ----- -psql -p 1521 ----- +Connect to the database with psql through port 1521 (the Oracle compatibility port) and perform the following verifications: + +. Verify the component's main functionality following the same testing method as in PG mode; +. Test the component's data type compatibility in Oracle compatibility mode; +. Test whether the component's functionality supports Oracle-style anonymous blocks, stored procedures, functions, etc. + +Record whether each function is available in Oracle compatibility mode; this serves as the basis for the functional coverage statement in the adaptation document. -. Test data type compatibility in Oracle compatibility mode -. Test whether component functionality supports Oracle-style anonymous blocks, stored procedures, functions, etc. -. Document all compatibility issues and solutions +Please note two things when testing: + +* *Write test statements using Oracle syntax.* Some syntax in Oracle compatibility mode differs from PG mode, so you cannot simply copy the PG-mode test cases. For example: the `interval` type must use Oracle-style syntax rather than PG syntax; statements such as `CREATE FUNCTION` and `CREATE PROCEDURE` must end with a `/` on its own line as the terminator. +* *Distinguish between "output differences" and "functional issues."* Some output that differs from PG mode is normal and should not be recorded as a compatibility issue. For example, type names in some output may carry a `pg_catalog.` schema prefix. To judge whether a function works normally, base it on whether the execution result is semantically correct, rather than requiring the output text to match the PG mode character for character. + +Record whether each function is available in Oracle compatibility mode; this serves as the basis for the functional coverage statement in the adaptation document. [NOTE] -Not all components support Oracle compatibility mode. If a component relies on PostgreSQL-specific internal mechanisms (such as using the `pg_query` module for statement parsing), it may not work in Oracle compatibility mode. This must be clearly stated in the documentation. +Not all components can work in Oracle compatibility mode. If running `CREATE EXTENSION` or calling a component function fails due to a syntax error, it is usually because the component internally uses PG-specific syntax that Oracle does not support; please refer to the PG syntax whitelist mechanism in the next section to fix it. If the component fundamentally conflicts with Oracle compatibility mode at the underlying-mechanism level (such as pg_partman), you must clearly state this in the adaptation document and the PR description. + +==== Fix Compatibility Issues via the PG Syntax Whitelist + +A common reason why Oracle compatibility mode testing fails — especially when `CREATE EXTENSION` fails outright — is that the extension is implemented through SQL scripts that make heavy use of PG-specific syntax that Oracle does not support (such as PG-style `interval` expressions and array slicing), so the scripts cannot pass syntax parsing under Oracle compatibility mode. + +To address this, the IvorySQL kernel provides a PG syntax whitelist mechanism (see the `PgDialectExtensions` list in `src/backend/commands/extension.c`). After an extension is added to the whitelist, running `CREATE EXTENSION` in an Oracle compatibility mode cluster will: + +* Temporarily parse and execute the extension's install script with the PG parser, unaffected by the current session's compatibility mode; +* Automatically inject the `SET ivorysql.compatible_mode = pg` setting into the functions created by the install script, so that no matter which compatibility mode the calling session uses, the function body is always parsed and executed by the PG parser. + +With this mechanism, extensions implemented using PG-specific syntax can be installed and run normally in an Oracle compatibility mode cluster without modifying any code. The whitelist currently includes extensions such as pg_profile and pg_repack. + +This approach applies to: + +* Extensions that are mainly implemented in SQL or PL/pgSQL and fail `CREATE EXTENSION` or function calls in Oracle compatibility mode because they use PG-specific syntax; +* Extensions whose functionality is self-contained (such as management-type extensions for statistics collection, table reorganization, etc.), where users only call their entry functions and do not require their internal implementation to interact with Oracle-style objects. + +This approach does not apply to: + +* Extensions that need to interact deeply with user-created Oracle-style objects (stored procedures, Oracle-specific data types, etc.); forcing them to be parsed as PG syntax would break such interaction; +* Extensions that fundamentally conflict with Oracle compatibility mode at the underlying-mechanism level (such as pg_partman, which depends on PostgreSQL's native partitioned-table management). Such problems are not at the syntax-parsing level and cannot be solved by the whitelist; you must still state the limitation in the adaptation document and the PR description. + +Once you confirm that the target extension falls into the applicable scenario, you can open a PR against the IvorySQL repository to add the extension name to the `PgDialectExtensions` whitelist, and attach the test results from both modes in the PR description; at the same time, state in the "Oracle Compatibility" section of the adaptation document that the extension runs through the whitelist mechanism. === Step 4: Documentation Writing @@ -161,13 +161,13 @@ Each ecosystem component adaptation document should include the following sectio |Detailed installation steps, including dependency installation, source acquisition, compilation, extension creation, etc. |Configuration -|(Optional) If the component requires additional configuration steps (such as modifying `ivorysql.conf`, restarting services, etc.), explain them here +|If the component requires additional configuration steps (such as modifying `ivorysql.conf`, restarting services, etc.), explain them here |Usage |Usage examples for core functionality, including object creation, operation execution, query results, etc. |Oracle Compatibility -|(Optional) Component behavior in Oracle compatibility mode, including supported features and known limitations +|Component behavior in Oracle compatibility mode, including supported features and known limitations |=== ==== Document Template @@ -251,7 +251,7 @@ Both the Chinese and English versions of the overview page need to be updated. ==== Create Branch -Create a feature branch in your forked repository: +Ecosystem component adaptation documents are submitted to the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository (note: this is not the IvorySQL main repository where you create Issues). Please first fork the repository and clone it locally, then create a feature branch: [literal] ---- @@ -263,25 +263,32 @@ git checkout -b feature/adapt- . Place the documentation file in the `CN/modules/ROOT/pages/master/ecosystem_components/` directory . If there are image resources, place them in the `CN/modules/ROOT/images/` directory . Prepare the English version simultaneously and place it in the corresponding EN directory -. Update both CN and EN `nav.adoc` and `ecosystem_overview.adoc` +. Update the links in both the CN and EN `nav.adoc` and `ecosystem_overview.adoc` -==== Submit PR +==== Create PR -. Link the corresponding Issue number in the PR title or description (e.g., `Fixes #123`) +. Open a PR against the `master` branch of the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository. +. Use `Fixes IvorySQL/IvorySQL#` in the PR description to link the adaptation Issue you claimed or created in Step 1 . In the PR description, explain: * The adapted component name and version * Test environment information * Completed test items * Known limitations or issues +[NOTE] +==== +. Since the Issue lives in the IvorySQL main repository, you must use the full reference format `IvorySQL/IvorySQL#`; once the PR is merged, the corresponding Issue is closed automatically. +. The linking keyword must be written in the PR description submitted to the IvorySQL docs repository and spelled correctly (`Fixes`/`Closes`/`Resolves` + a space + `IvorySQL/IvorySQL#`); writing it in a comment has no effect. +==== + ==== Await Review -Maintainers will review the PR and may suggest the following modifications: +Maintainers will reproduce the test following the steps in the document and review the PR. They may suggest the following modifications: * Add missing test cases * Fix documentation format issues * Improve Oracle compatibility testing -* Add English translation +* Add the English translation Please revise and update the PR promptly based on review feedback. @@ -303,6 +310,7 @@ Please check: . Whether the extension's `.so` file is correctly installed in IvorySQL's `lib` directory . Whether the extension's `.sql` and `.control` files are correctly installed in the `share/extension` directory . Whether the IvorySQL version is compatible with the PostgreSQL version required by the component +. If the failure is caused by PG-specific syntax that cannot be parsed, refer to the PG syntax whitelist mechanism in Step 3. === Functionality Issues in Oracle Compatibility Mode @@ -310,4 +318,5 @@ Some PostgreSQL extensions rely on the native PG parser and may not work correct === Unsure Whether a Component Is Suitable for Adaptation -Please start a discussion in https://github.com/IvorySQL/ivorysql_docs[Issues], describing the component's functionality and your adaptation plan. Maintainers will provide an assessment. +Please start a discussion in https://github.com/IvorySQL/IvorySQL/issues[Issues], describing the component's functionality and your adaptation plan. Maintainers will provide an assessment. + From f80bd4e54426b8a6927ae124c3a3f96c9541fd68 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 13:53:04 +0800 Subject: [PATCH 03/10] docs: consolidate contribution guides into single unified guide Merge community_contribution_guide.adoc and ecosystem_contribution_guide.adoc into a single contribution_guide.adoc for both Chinese and English versions. Changes: - Create unified contribution_guide.adoc combining all contribution content - Remove separate community and ecosystem contribution guide files - Update navigation in both CN and EN nav.adoc files - Content covers: community workflow, roles, getting started, code contributions, and ecosystem component adaptation This consolidation provides a single entry point for all contribution-related information, eliminating content duplication and improving user experience. --- CN/modules/ROOT/nav.adoc | 3 +- .../community_contribution_guide.adoc | 188 --- ...ion_guide.adoc => contribution_guide.adoc} | 284 ++++- EN/modules/ROOT/nav.adoc | 3 +- .../community_contribution_guide.adoc | 1003 ----------------- ...ion_guide.adoc => contribution_guide.adoc} | 284 ++++- 6 files changed, 502 insertions(+), 1263 deletions(-) delete mode 100644 CN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc rename CN/modules/ROOT/pages/master/contribution/{ecosystem_contribution_guide.adoc => contribution_guide.adoc} (53%) delete mode 100644 EN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc rename EN/modules/ROOT/pages/master/contribution/{ecosystem_contribution_guide.adoc => contribution_guide.adoc} (53%) diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index b5f0e10..4d274a5 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -80,8 +80,7 @@ * 数据迁移 ** xref:master/migration_guide.adoc[迁移指南] * IvorySQL开发者 -** xref:master/contribution/community_contribution_guide.adoc[社区贡献指南] -** xref:master/contribution/ecosystem_contribution_guide.adoc[生态组件适配贡献指南] +** xref:master/contribution/contribution_guide.adoc[贡献指南] ** xref:master/developer_guide.adoc[开发者指南] ** IvorySQL架构设计 *** 查询处理 diff --git a/CN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc deleted file mode 100644 index fadfeb7..0000000 --- a/CN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc +++ /dev/null @@ -1,188 +0,0 @@ - -:sectnums: -:sectnumlevels: 5 - -:imagesdir: ./_images -== **IvorySQL社区协作流程** - -IvorySQL 社区采用一套 闭环式开源协作流程，确保从问题提出到版本发布，每一个环节都能闭合反馈、持续改进。这一流程鼓励用户与开发者形成良性互动，让社区开发始终围绕实际需求持续演进。 - -整个协作闭环流程如下： - -🐛 提问题（Issue） - -用户或开发者在 GitHub 的 Issues 页面提交 Bug、功能建议或使用反馈。 - -💬 问题讨论（Discussion） - -维护者与社区成员就问题展开讨论，确认问题性质与优先级，加入 ToDo List。 - -🛠️ 开发分支（Fork & Dev） - -开发者认领 Issue，Fork 仓库并在本地开发测试，准备提交代码。 - -🚀 提交 Pull Request（PR） - -将开发分支 Push 到 Fork 仓库后，向上游仓库发起合并请求。 - -🧐 代码评审（Review） - -维护者或核心开发者对 PR 进行评审，提出修改建议并确保质量。 - -🔀 合并主分支（Merge） - -审核通过后，PR 被合并至主分支，对应的 Issue 被关闭。 - -📦 版本发布（Release） - -项目定期发布新版本（每季度小版本，每年大版本），包含最新的修复与功能。 - -🧪 用户测试（Test） - -用户升级使用新版，反馈新问题，新的 Issue 随之产生，形成完整的反馈循环。 - -image::p23.jpg[] - -通过这套完整的闭环协作机制，IvorySQL 实现了问题响应 → 开发贡献 → 质量保障 → 发布反馈的全流程闭合，推动项目持续健康演进。 - -== **IvorySQL社区贡献指南** - -IvorySQL是一个由核心开发团队主导、社区共同维护的开源项目。我们欢迎用户、贡献者和维护者的加入，共同推动IvorySQL的发展。如果您希望看到您的代码或文档更改被添加到IvorySQL并出现在将来的版本中，本节的内容介绍是您需要知道的。 - -在参与贡献前，请确认您当前的参与身份，以便更高效地了解适合您的贡献方式： - -* 用户 👉 欢迎提交问题反馈、功能建议，并参与社区讨论。 - -* 贡献者 👉 请先签署 CLA，然后选择您感兴趣的项目模块进行 Issue 认领和代码提交。 - -* 维护者 👉 请参考维护职责，包括社区规划、代码评审和协作机制建设。 - -无论您以何种身份加入，IvorySQL 社区都非常欢迎您的参与和支持！​IvorySQL社区欢迎并赞赏所有类型的贡献，期待您的加入！ - -📢 请务必阅读并遵守我们的 https://github.com/IvorySQL/IvorySQL/blob/master/CODE_OF_CONDUCT_CN.md[IvorySQL社区行为准则]。 - -=== 注册Github账号 - -无论您是要提交 Issue、参与讨论，还是贡献代码与文档，您都需要使用 GitHub 账号登录并与 IvorySQL 项目进行交互。 - -请参考注册您的github账号，并熟悉Git工具和工作流。 - -IvorySQL源码托管在github: 。 - -=== 用户 - -作为用户，您在使用 IvorySQL 过程中扮演着重要角色。我们鼓励您： - -==== 反馈问题与需求 - -* 发现 Bug、性能缺陷或文档不准确？ - -* 有新的功能建议或使用体验改进？ - -如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考Issue xref:master/contribution/issue_submission_guide.adoc[提交指南]。 - -==== 参与社区讨论 - -* 通过 https://lists.ivorysql.org[邮件列表]进行讨论 - -* 加入 https://github.com/IvorySQL/IvorySQL/discussions[GitHub讨论]，补充信息或验证问题 - -* 在 微信、Discord等聊天群参与技术交流 - -=== 贡献者 - -我们欢迎代码、文档、测试等各类贡献。 - -==== 文档贡献 - -如果您新增或更新某个插件适配文档，请同步更新 xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc] 概述页面中的插件表格，至少补充或更新插件名称、版本、功能描述、适用场景以及详情页链接，确保概述页与插件详情页信息一致。 - -==== 签署CLA -在提交代码或文档贡献之前，为了确保代码合法合规，个人或企业贡献者需要签署贡献者许可协议(CLA)。签署CLA是IvorySQL社区接受贡献的必要条件，以确保您的贡献被合法分发。请根据下列链接下载CLA进行签署并将签署后的CLA发送至 cla@ivorysql.org。 - -* https://www.ivorysql.org/zh-CN/assets/files/individual_cla-a81f001209eb5ce0f8ea7c3be4cc69b5.pdf[个人贡献者] -* https://www.ivorysql.org/zh-CN/assets/files/corporate_cla-76e89b6f17b0bc102cbc1105d438a917.pdf[企业贡献者] - -未签署CLA的Pull Request将无法进入评审阶段。 - -==== 找到您感兴趣的项目 - -我们将仓库划分为多个子项目，您可以从如下列表中找到感兴趣的项目及其代码仓库 - -[cols="1,1"] -|=== -|代码仓库 | 描述 -|https://github.com/IvorySQL/IvorySQL[IvorySQL] | 负责社区IvorySQL数据库的开发和维护 -|https://github.com/IvorySQL/Ivory-www[Ivory-www] | 负责社区的官网开发和维护 -|https://github.com/IvorySQL/ivory-operator[ivory-operator] | 负责IvorySQL云原生数据库及周边工具开发和维护 -|https://github.com/IvorySQL/docker_library[docker_library] | 负责IvorySQL多架构的镜像构建开发和维护 -|https://github.com/IvorySQL/ivory-cloud[ivory-cloud] | 负责IvorySQL云服务平台及周边生态开发和维护 -|https://github.com/IvorySQL/ivorysql_docs[Ivorysql_docs] | 负责社区的文档中心开发和维护 -|https://github.com/IvorySQL/ivory-doc-builder[ivory-doc-builder] | 负责Ivorysql_docs的编译 -|https://github.com/IvorySQL/ivorysql_web[Ivorysql_web] | 负责社区的文档中心网站维护 -|https://github.com/IvorySQL/ivorysql-wasm[Ivorysql_wasm] | 负责IvorySQL在线易用体验网站的开发和维护 -|=== - -==== 给自己分配Issue -您可以将自己创建的Issue或者愿意处理的Issue分配给自己。 只需要在评论框内输入/assign，机器人就会将问题分配给您。 每个 Issue 下面可能已经有参与者的交流和讨论，如果您感兴趣，也可以在评论框中发表自己的意见参与 Issue 讨论。 - -==== 开发与提交Pull Request -对于提交一个PR应该保持一个功能，或者一个bug提交一次。禁止多个功能一次提交。 - -提交 GitHub PR 之前，请先创建或认领对应的 Issue。所有 PR 都必须有至少一个对应的 Issue，用于关联需求、缺陷、讨论、评审和合并结果；没有对应 Issue 的 PR 不符合社区贡献流程。 - -===== Fork仓库 - -前往项目主页，点击Fork按钮，将IvorySQL项目Fork到您自己的GitHub账户中。 - -===== 编码 - -使用如下命令将项目克隆到本地进行开发： - -git clone https://github.com/$user/IvorySQL.git （将 $user 替换为你的 GitHub ID）。 - -git checkout -b feature/your-feature-name - -在提交代码前，请确保通过回归测试 - -===== 创建一个Pull Request并提交 - -打开你 Fork 的仓库： https://github.com/$user/IvorySQL.git - -点击 Compare & pull request 按钮填写PR信息 - -``` -Fix test -功能描述 -``` -``` -leave a comment -对该提交功能进行比较详细的描述 -``` - -请在 PR 标题或描述中显式关联对应 Issue 编号，例如 `Fixes #123` 或 `Refs #123`。 - -点击Create pull request 按钮即可提交。 - -=== 维护者 -维护者负责进行IvorySQL代码的管理，PR审查，主导版本发布与IvorySQL发展方向。 - -==== 社区规划 -* 制定版本规划和 Roadmap - -* 跟踪与评估社区需求 - -* 维护公开的 TODO 列表 - -==== 代码管理 -* 参与 Pull Request 评审 - -* 审查安全问题，保障项目健康 - -==== 流程与治理机制 -* 优化协作机制（代码贡献指南、PR 模板等） - -* 建立漏洞响应机制和行为守则 - -=== 致谢 -感谢每一位参与 IvorySQL 的开发者、文档编辑者、测试人员和使用者。正是有了你们的付出，IvorySQL 才能不断成长！我们欢迎所有人参与 IvorySQL 社区贡献，我们的目标是发展一个由贡献者组成的活跃、健康的社区。 diff --git a/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc similarity index 53% rename from CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc rename to CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 6234786..3dc803b 100644 --- a/CN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -1,15 +1,228 @@ :sectnums: :sectnumlevels: 5 -= 生态组件适配贡献指南 +:imagesdir: ./_images -== 概述 += IvorySQL 贡献指南 -IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 +IvorySQL 的成长离不开来自世界各地的开发者、测试人员、文档作者、翻译者、社区布道师和用户的贡献。本指南将帮助您了解如何参与 IvorySQL 社区，从入门到深入贡献的完整路径。 + +== 贡献方式 + +IvorySQL 社区相信开源应当触手可及，每一份贡献都弥足珍贵。您可以根据自己的背景和兴趣选择参与方式： + +* *代码贡献*：内核开发、功能迭代、Bug 修复、插件开发、生态工具适配、回归测试、代码评审 +* *非代码贡献*：Issue 反馈、文档改进、技术翻译、社区问答、线上线下分享、案例研究、迁移经验分享、社区推广 + +如果您还不确定如何开始，也可以通过复现问题、澄清需求、改进文档或在社区讨论中帮助其他用户来做出有意义的贡献。 + +== 激励政策 + +为鼓励长期参与，IvorySQL 社区持续完善贡献者认可与支持机制： + +* *认可机制*：贡献者可获得社区数字证书，并展示在官方 https://www.ivorysql.org/contributors[贡献者墙]，记录您的开源足迹 +* *导师计划*："灯塔"导师模式，提供技术指导和一对一支持，经验丰富的社区成员将进行代码评审反馈 +* *社区机会*：活跃贡献者可获得 HOW 等技术活动的演讲、分享或参与机会 +* *年度激励*：社区将评选优秀贡献者，提供周边、公开表彰、生态曝光等合作机会 + +具体安排可能随社区项目调整，但持续且有价值的贡献始终会被认真对待和认可。 + +如果您对代码贡献感兴趣但不确定从何开始，或者这是您第一次贡献 IvorySQL，下面的指南将帮助您找到清晰的切入点。 + +== 社区协作流程 + +IvorySQL 社区采用一套闭环式开源协作流程，确保从问题提出到版本发布，每一个环节都能闭合反馈、持续改进。这一流程鼓励用户与开发者形成良性互动，让社区开发始终围绕实际需求持续演进。 + +整个协作闭环流程如下： + +🐛 *提问题（Issue）* + +用户或开发者在 GitHub 的 Issues 页面提交 Bug、功能建议或使用反馈。 + +💬 *问题讨论（Discussion）* + +维护者与社区成员就问题展开讨论，确认问题性质与优先级，加入 ToDo List。 + +🛠️ *开发分支（Fork & Dev）* + +开发者认领 Issue，Fork 仓库并在本地开发测试，准备提交代码。 + +🚀 *提交 Pull Request（PR）* + +将开发分支 Push 到 Fork 仓库后，向上游仓库发起合并请求。 + +🧐 *代码评审（Review）* + +维护者或核心开发者对 PR 进行评审，提出修改建议并确保质量。 + +🔀 *合并主分支（Merge）* + +审核通过后，PR 被合并至主分支，对应的 Issue 被关闭。 + +📦 *版本发布（Release）* + +项目定期发布新版本（每季度小版本，每年大版本），包含最新的修复与功能。 + +🧪 *用户测试（Test）* + +用户升级使用新版，反馈新问题，新的 Issue 随之产生，形成完整的反馈循环。 + +image::p23.jpg[] + +通过这套完整的闭环协作机制，IvorySQL 实现了问题响应 → 开发贡献 → 质量保障 → 发布反馈的全流程闭合，推动项目持续健康演进。 + +📢 请务必阅读并遵守我们的 https://github.com/IvorySQL/IvorySQL/blob/master/CODE_OF_CONDUCT_CN.md[IvorySQL社区行为准则]。 + +== 角色与职责 + +在参与贡献前，请确认您当前的参与身份，以便更高效地了解适合您的贡献方式： + +=== 用户 + +作为用户，您在使用 IvorySQL 过程中扮演着重要角色。我们鼓励您： + +==== 反馈问题与需求 + +* 发现 Bug、性能缺陷或文档不准确？ +* 有新的功能建议或使用体验改进？ + +如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考 Issue xref:master/contribution/issue_submission_guide.adoc[提交指南]。 + +==== 参与社区讨论 + +* 通过 https://lists.ivorysql.org[邮件列表]进行讨论 +* 加入 https://github.com/IvorySQL/IvorySQL/discussions[GitHub讨论]，补充信息或验证问题 +* 在微信、Discord 等聊天群参与技术交流 + +=== 贡献者 + +我们欢迎代码、文档、测试等各类贡献。 + +==== 找到您感兴趣的项目 + +我们将仓库划分为多个子项目，您可以从如下列表中找到感兴趣的项目及其代码仓库： + +[cols="1,1"] +|=== +|代码仓库 | 描述 + +|https://github.com/IvorySQL/IvorySQL[IvorySQL] | 负责社区 IvorySQL 数据库的开发和维护 +|https://github.com/IvorySQL/Ivory-www[Ivory-www] | 负责社区的官网开发和维护 +|https://github.com/IvorySQL/ivory-operator[ivory-operator] | 负责 IvorySQL 云原生数据库及周边工具开发和维护 +|https://github.com/IvorySQL/docker_library[docker_library] | 负责 IvorySQL 多架构的镜像构建开发和维护 +|https://github.com/IvorySQL/ivory-cloud[ivory-cloud] | 负责 IvorySQL 云服务平台及周边生态开发和维护 +|https://github.com/IvorySQL/ivorysql_docs[Ivorysql_docs] | 负责社区的文档中心开发和维护 +|https://github.com/IvorySQL/ivory-doc-builder[ivory-doc-builder] | 负责 Ivorysql_docs 的编译 +|https://github.com/IvorySQL/ivorysql_web[Ivorysql_web] | 负责社区的文档中心网站维护 +|https://github.com/IvorySQL/ivorysql-wasm[Ivorysql_wasm] | 负责 IvorySQL 在线易用体验网站的开发和维护 +|=== + +==== 给自己分配 Issue + +您可以将自己创建的 Issue 或者愿意处理的 Issue 分配给自己。只需要在评论框内输入 `/assign`，机器人就会将问题分配给您。每个 Issue 下面可能已经有参与者的交流和讨论，如果您感兴趣，也可以在评论框中发表自己的意见参与 Issue 讨论。 + +=== 维护者 + +维护者负责进行 IvorySQL 代码的管理，PR 审查，主导版本发布与 IvorySQL 发展方向。 + +==== 社区规划 + +* 制定版本规划和 Roadmap +* 跟踪与评估社区需求 +* 维护公开的 TODO 列表 + +==== 代码管理 + +* 参与 Pull Request 评审 +* 审查安全问题，保障项目健康 + +==== 流程与治理机制 + +* 优化协作机制（代码贡献指南、PR 模板等） +* 建立漏洞响应机制和行为守则 + +== 入门准备 + +=== 注册 GitHub 账号 + +无论您是要提交 Issue、参与讨论，还是贡献代码与文档，您都需要使用 GitHub 账号登录并与 IvorySQL 项目进行交互。 + +请参考 注册您的 GitHub 账号，并熟悉 Git 工具和工作流。 + +IvorySQL 源码托管在 GitHub：。 + +=== 签署 CLA + +在提交代码或文档贡献之前，为了确保代码合法合规，个人或企业贡献者需要签署贡献者许可协议（CLA）。签署 CLA 是 IvorySQL 社区接受贡献的必要条件，以确保您的贡献被合法分发。请根据下列链接下载 CLA 进行签署并将签署后的 CLA 发送至 cla@ivorysql.org。 + +* https://www.ivorysql.org/zh-CN/assets/files/individual_cla-a81f001209eb5ce0f8ea7c3be4cc69b5.pdf[个人贡献者] +* https://www.ivorysql.org/zh-CN/assets/files/corporate_cla-76e89b6f17b0bc102cbc1105d438a917.pdf[企业贡献者] + +未签署 CLA 的 Pull Request 将无法进入评审阶段。 + +== 代码贡献 + +=== 环境准备 + +IvorySQL 的开发和协作在 GitHub 上进行。在贡献之前，建议您： -本文档旨在为有意参与生态组件适配的贡献者提供完整的指引，涵盖从选题、环境准备、适配测试、文档编写到提交贡献的全流程。 +* 拥有 GitHub 账号并熟悉基本的 Git 工作流 +* Fork 官方仓库，并在自己的 Fork 中 dedicated 分支上工作 +* 关注社区讨论或邮件列表，特别是对于较大的提案 -== 适配范围 +=== 补丁提交 + +我们推荐以下贡献流程： + +. 从 GitHub Issues、文档空白、社区活动或生态需求中选择一个切入点 +. 对于较大的变更，先在 Issue、PR 讨论或邮件列表中讨论提案，减少返工 +. Fork 仓库并为一个自包含的变更创建 dedicated 分支 +. 完成实现、测试或文档更新，并在本地审查您的变更 +. 向官方仓库提交 Pull Request，或对非代码贡献使用 Issues 和 Discussions +. 响应评审反馈，必要时推送后续提交，迭代直到变更准备好合并 + +=== 编码和测试指南 + +为提高评审质量和合并效率，我们建议： + +* 尽可能将较大的想法拆分为一系列小型、自包含的提交 +* 对于 C 和 C++ 相关变更，遵循 PostgreSQL 编码约定 +* 需要时对 C 和 Perl 代码运行 `pgindent` +* 提交前使用 `git diff --color` 检查意外的空白变更 +* 为新功能添加回归测试 +* 至少运行 `make installcheck-world` 确保您的变更没有引入明显的回归 + +如果您不确定如何测试或记录变更，请在 `ivorysql-hackers` 邮件列表中提问，社区将尽力提供帮助。 + +=== 贡献的许可 + +如果您提交的贡献是原创作品，您可以假设它将作为 IvorySQL 整体版本的一部分发布，该版本遵循 Apache License 2.0。 + +如果贡献不是原创作品，您必须明确指出原始许可证并确保其与 Apache License 2.0 条款兼容。可能还需要适当的归属。通常情况下，除非您绝对确定这样做是合适的，否则不要删除第三方或先前授权工作中现有的许可证头部。 + +如果您不确定贡献的许可影响，请在提交前联系社区。 + +=== 适用于 PostgreSQL 上游的变更 + +如果您的变更涉及 PostgreSQL 和 IvorySQL 共享的功能，社区可能会要求您向前移植或向上游提议该变更。这有助于减少两个项目之间的长期分歧，并让广泛适用的变更在 PostgreSQL 生态系统中获得更广泛的评审。 + +=== 补丁评审 + +提交的通过检查的 Pull Request 被视为可供同行评审。同行评审有助于确保变更符合项目质量标准、路线图方向和社区期望。 + +可能的评审结果包括请求额外提交、范围变更、测试改进或文档更新。请不要因迭代而气馁；这是开源协作的正常部分。 + +当反馈延迟时，可以在 Pull Request 上留下礼貌的评论或通过社区渠道询问更新。 + +=== 直接提交 + +有时，核心团队成员可能会直接提交小的非功能性修复。影响行为、测试或产品功能的变更应通过 Pull Request 工作流。 + +== 生态组件适配 + +IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 + +=== 适配范围 以下类型的组件欢迎贡献者进行适配： @@ -17,19 +230,19 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 * 基于 PostgreSQL 扩展机制开发的第三方插件 * 以独立进程形式与数据库配合工作的周边生态工具，如连接池、代理、中间件等 -== 贡献流程 +=== 贡献流程 生态组件适配，是将 PostgreSQL 生态组件适配到 IvorySQL 的工作。主要内容包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档，提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库。文档提交后，维护者会按照适配文档中给出的步骤对目标组件进行复现测试，确认测试结果与文档描述一致后，合并该 PR。 具体的选题、测试、文档编写等环节，请参考下面的详细步骤。 -=== 第一步：选题与沟通 +==== 第一步：选题与沟通 -==== 确认组件未被适配 +===== 确认组件未被适配 在开始适配工作之前，请先查阅 xref:master/ecosystem_components/ecosystem_overview.adoc[生态组件适配列表]，确认目标组件是否已完成适配。如果目标组件不在列表中，则继续后面的流程；否则，请重新选择一个未适配的组件。 -==== 认领或新建 Issue +===== 认领或新建 Issue 在 IvorySQL 仓库的 https://github.com/IvorySQL/IvorySQL/issues[Issue 列表] 中搜索目标组件： @@ -41,13 +254,13 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 [TIP] 建议在 Issue 获得维护者确认后再开始适配工作，避免重复或无效工作。 -==== 签署 CLA +===== 签署 CLA -在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅 xref:master/contribution/community_contribution_guide.adoc[社区贡献指南] 中的 CLA 签署说明。 +在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的 xref:#_签署_cla[签署 CLA] 章节。 -=== 第二步：环境准备 +==== 第二步：环境准备 -==== IvorySQL 环境 +===== IvorySQL 环境 请准备一套可用于测试的 IvorySQL 环境，建议满足以下要求： @@ -58,7 +271,7 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 [TIP] 可以通过 IvorySQL 官方提供的 Docker 镜像快速搭建测试环境，参考 xref:master/containerization/docker_podman_deployment.adoc[Docker & Podman 部署]。 -==== 编译工具链 +===== 编译工具链 根据目标组件的编译方式，准备相应的工具链： @@ -66,18 +279,18 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 * Rust 扩展：需要 cargo、rustc 等 Rust 工具链 * 其他语言扩展：需要对应语言的运行环境 -=== 第三步：适配测试 +==== 第三步：适配测试 生态组件适配的目标分为两个层面： - PG 模式：组件必须完全可用。 - Oracle 兼容模式：应尽可能做到完全可用；若无法完全可用，至少应保证主要功能可以正常运行。对于底层机制与 Oracle 兼容模式冲突、完全无法在该模式下运行的 PG 专用扩展（例如 pg_partman 专为管理 PostgreSQL 分区表而设计，不支持在 Oracle 兼容模式下运行），需在适配文档和 PR 描述中说明情况。 -==== 组件编译安装 +===== 组件编译安装 请参考目标组件的官方文档进行编译安装。 -==== 测试 PG 模式 +===== 测试 PG 模式 启动 IvorySQL 实例，使用 psql 通过 5432 端口连接数据库，进行以下验证： @@ -98,7 +311,7 @@ ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; 如果某个功能无法使用或测试失败，需排查原因：属于 IvorySQL 侧的问题，请向 IvorySQL 仓库提交 PR 修复；属于组件侧的问题，可向组件仓库反馈，并在适配文档中记录该限制。 -==== 测试 Oracle 兼容模式 +===== 测试 Oracle 兼容模式 使用 psql 通过 1521 端口（Oracle 兼容端口）连接数据库，进行以下验证： @@ -111,14 +324,14 @@ ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; 测试时请注意以下两点： * *使用 Oracle 语法编写测试语句*。Oracle 兼容模式下的部分语法与 PG 模式不同，不能直接照搬 PG 模式的测试用例。例如：interval 类型需使用 Oracle 风格的语法，而非 PG 语法；`CREATE FUNCTION`、`CREATE PROCEDURE` 等语句需在末尾另起一行加 `/` 作为结束符。 -* *区分“输出差异”与“功能异常”*。部分输出与 PG 模式不一致属于正常现象，不应记为兼容性问题。例如：某些输出中的类型名会带有 `pg_catalog.` 模式前缀。判断功能是否正常，应以执行结果的语义是否正确为准，而不要求输出文本与 PG 模式逐字一致。 +* *区分"输出差异"与"功能异常"*。部分输出与 PG 模式不一致属于正常现象，不应记为兼容性问题。例如：某些输出中的类型名会带有 `pg_catalog.` 模式前缀。判断功能是否正常，应以执行结果的语义是否正确为准，而不要求输出文本与 PG 模式逐字一致。 记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。 [NOTE] 并非所有组件都能在 Oracle 兼容模式下工作。如果执行 `CREATE EXTENSION` 或调用组件功能时因语法错误而失败，多是组件内部使用了 Oracle 不支持的 PG 专用语法所致，请参考下一节的 PG 语法白名单机制进行修复；如果组件与 Oracle 兼容模式在底层机制上冲突（如 pg_partman），则需要在适配文档和 PR 描述中明确说明。 -==== 通过 PG 语法白名单修复兼容问题 +===== 通过 PG 语法白名单修复兼容问题 Oracle 兼容模式测试不通过——尤其是执行 `CREATE EXTENSION` 就直接失败——的一个常见原因是：扩展通过 SQL 脚本实现，脚本中大量使用了 Oracle 不支持的 PG 专用语法（如 PG 风格的 interval 表达式、数组切片等），导致脚本无法通过 Oracle 兼容模式下的语法解析。 @@ -141,11 +354,11 @@ Oracle 兼容模式测试不通过——尤其是执行 `CREATE EXTENSION` 就 确认目标扩展属于适用场景后，您可以向 IvorySQL 仓库提交 PR，将扩展名加入 `PgDialectExtensions` 白名单，并在 PR 描述中附上两种模式下的测试结果；同时在适配文档的 "Oracle 兼容性" 章节中说明该扩展通过白名单机制运行。 -=== 第四步：文档编写 +==== 第四步：文档编写 IvorySQL 文档使用 AsciiDoc 编写的，其语法与 Markdown 类似但功能更加强大。如果不熟悉 AsciiDoc 语法，可参阅 xref:master/contribution/asciidoc_syntax_reference.adoc[asciidoc语法快速参考]。 -==== 文档结构 +===== 文档结构 每篇生态组件适配文档应包含以下章节（可根据组件特点适当调整）： @@ -172,7 +385,7 @@ IvorySQL 文档使用 AsciiDoc 编写的，其语法与 Markdown 类似但功能 |组件在 Oracle 兼容模式下的表现，包括支持的功能和已知限制 |=== -==== 文档模板 +===== 文档模板 以下是一个生态组件适配文档的基础模板，贡献者可以在此基础上填充内容： @@ -236,7 +449,7 @@ ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; <可选：在 Oracle 兼容模式下的测试结果> ------ -==== 同步更新概述页 +===== 同步更新概述页 完成组件文档编写后，请务必同步更新 xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc] 中的插件列表表格，在表格末尾追加一行新记录，包含以下信息： @@ -249,9 +462,9 @@ ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; [NOTE] 中英文版本的概述页都需要同步更新。 -=== 第五步：提交 PR +==== 第五步：提交 PR -==== 创建分支 +===== 创建分支 生态组件适配文档统一提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库（注意：不是创建 Issue 的 IvorySQL 主仓库）。请先 fork 该仓库并 clone 到本地，然后创建特性分支： @@ -260,14 +473,14 @@ ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; 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 +===== 创建 PR . 向 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库的 master 分支提交 PR . 在 PR 描述中使用 `Fixes IvorySQL/IvorySQL#<编号>` 关联第一步中认领或新建的适配 Issue @@ -283,7 +496,7 @@ git checkout -b feature/adapt-<组件名称> . 关联关键字必须写在 IvorySQL docs 仓库提交的 PR 描述中且拼写规范（`Fixes`/`Closes`/`Resolves` + 空格 + `IvorySQL/IvorySQL#<编号>`），写在评论里无效。 ==== -==== 等待评审 +===== 等待评审 维护者会按照文档中的步骤复现测试，并对 PR 进行评审，可能会提出以下修改建议： @@ -294,9 +507,9 @@ git checkout -b feature/adapt-<组件名称> 请根据评审意见及时修改并更新 PR。 -== 常见问题 +=== 常见问题 -=== 编译报错找不到 pg_config +==== 编译报错找不到 pg_config 请确认 `PG_CONFIG` 环境变量设置正确，指向 IvorySQL 安装目录下的 `bin/pg_config`。可以通过以下命令确认： @@ -305,7 +518,7 @@ git checkout -b feature/adapt-<组件名称> $PG_CONFIG --version ---- -=== 扩展创建失败 +==== 扩展创建失败 请检查： @@ -314,11 +527,14 @@ $PG_CONFIG --version . IvorySQL 版本是否与组件要求的 PostgreSQL 版本兼容 . 若失败原因是 PG 专用语法无法解析，可参考第三步的 PG 语法白名单机制。 -=== Oracle 兼容模式下功能异常 +==== Oracle 兼容模式下功能异常 部分 PostgreSQL 扩展依赖 PG 原生解析器，在 Oracle 兼容模式下可能无法正常工作。遇到此类问题时，请在文档的 "Oracle 兼容性" 章节中明确说明限制，并提供替代方案（如有）。 -=== 不确定组件是否适合适配 +==== 不确定组件是否适合适配 请先在 https://github.com/IvorySQL/IvorySQL/issues[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。 +== 致谢 + +感谢每一位参与 IvorySQL 的开发者、文档编辑者、测试人员和使用者。正是有了你们的付出，IvorySQL 才能不断成长！我们欢迎所有人参与 IvorySQL 社区贡献，我们的目标是发展一个由贡献者组成的活跃、健康的社区。 diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 38f0ef3..d295068 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -80,9 +80,8 @@ * Data Migration ** xref:master/migration_guide.adoc[Migration] * IvorySQL Developers +** xref:master/contribution/contribution_guide.adoc[Contribution Guide] ** 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] diff --git a/EN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc deleted file mode 100644 index c1cb5df..0000000 --- a/EN/modules/ROOT/pages/master/contribution/community_contribution_guide.adoc +++ /dev/null @@ -1,1003 +0,0 @@ - -:sectnums: -:sectnumlevels: 5 - -:imagesdir: ./_images -= **IvorySQL Community Contribution Guide** - -== **Summary** - -=== Illustration - -IvorySQL is maintained by a core development team, which has commit access to the main repository of IvorySQL on GitHub. We are eager to get contributions from members of the wider IvorySQL community. If you want to see your changes to code or documents added to IvorySQL and appear in future versions, you need to understand the content of this section. - -​IvorySQL community welcomes and appreciates all types of contributions and we are looking forward to your participation! - -=== Principles of Conduct - -Every member, contributor and leader should read our *principles of conduct*. We promise that everyone can participate in community and pay equal attention to everyone, no matter who. - -We are committed to acting and interacting in a way that contributes to the establishment of an open, enthusiastic, diverse, inclusive and healthy community. - -=== Description of Community Governance - -Our team is a continuously open team, focusing on parts of IvorySQL. In our team, there are reviewers, submitters and maintainers, and we have one or more repositories. The decision for the team is made by the maintainer. The typical promotion path for IvorySQL developers is from user to reviewer, then submitter and maintainer. But getting more roles doesn't mean you have any privileges to other community members. Everyone in the IvorySQL community is equal and has the responsibility to cooperate constructively with other contributors to build a friendly community. These roles are natural rewards for your significant contributions to the development of IvorySQL, and provide you with more rights in the development workflow to improve your efficiency. At the same time，this requires you to undertake some additional duty: - -​Team honor: now you are already one of the team reviewers/submitters/maintainers, it means that you represent the project and your team members. So, please be Mr.Nice Guy to defend the reputation of the team. - -​Responsibility: submitters/maintainers have the right to merge pull requests, therefore, they take additional responsibility to deal with the consequences of accepting changes to the code base or documents. When a bug occurs, they should fix it. If they can not solve it, they should roll back the project. Also, they need to help the release manager solve any problems found in the test cycle. - -== **Contributor's Guide** - -Before contributing, we need to know the current version of IvorySQL and the version of the document.At present, we maintain versions after version *5.0*. Our version follows the update pace of PG. Please update to the latest version before contributing. After that, we need to read the format requirements carefully and be familiar with code format, code comment format, issue format, pull PR title format, document contribution format, and article contribution format. These can help you become a contributor of IvorySQL as soon as possible. - - -=== Preparation before Contribution - -==== Getting started - -IvorySQL is developed on GitHub. Anyone who wishes to contribute to it must have a Github account and be familiar with Git tools and workflow. It is also recommended that you follow the developer's mailing list since some of the contributions may generate more detailed discussions there. - -Once you have your GitHub account, fork this repository so that you can have your private copy to start hacking on and to use as a source of pull requests. - -==== Licensing of IvorySQL contributions - -If the contribution you're submitting is original work, you can assume that IvorySQL will release it as part of an overall IvorySQL release available to the downstream consumers under **the Apache License, Version 2.0**. - -If the contribution you're submitting is NOT original work you have to indicate the name of the license and also make sure that it is similar in terms to the Apache License 2.0. Apache Software Foundation maintains a list of these licenses under Category A. In addition to that, you may be required to make proper attributions. - -Finally, keep in mind that it is NEVER a good idea to remove licensing headers from the work that is not your original one. Even if you are using parts of the file that originally had a licensing header at the top you should err on the side of preserving it. As always, if you are not quite sure about the licensing implications of your contributions, feel free to reach out to us on the developer mailing list. - - -=== What Contribution Can You Make - -==== Code Contribution - -You can upload your modified bugs, new functions and other codes to your personal warehouse, and finally submit PR requests to merge them on the official website: https://github.com/IvorySQL/IvorySQL. - - -==== Document Contribution(https://www.ivorysql.org/zh-CN/docs/intro) - -The IvorySQL community provides Chinese and English documents. English documents are saved in ... document repository, Chinese documents are saved in i18n document repository. You can contribute to one of them or both. - -When you add or update a plugin compatibility document, you must also update the plugin summary table in xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc]. Keep the plugin name, version, function description, use cases, and link to the detail page in sync so that the overview page and the detail page stay consistent. - -==== Test IvorySQL and Report Bugs - -GitHub: https://github.com/IvorySQL/IvorySQL - -Gitee:https://gitee.com/IvorySQL/ - -==== Participate in the Construction of IvorySQL Website - -IvorySQL official website:https://github.com/IvorySQL/Ivory-www - -==== Answer Questions on the Mailing List - -Mailing List website:https://lists.ivorysql.org/ - -==== Contribute Article - -You can submit your article to the blog in the IvorySQL-WWW code warehouse, or send it to the mailbox renjiao@highgo.com. - -=== How to Contribute - -==== Coding Guidelines - -Your chances of getting feedback and seeing your code merged into the project greatly depend on how granular your changes are. If you happen to have a bigger change in mind, we highly recommend engaging on the developer's mailing list first and sharing your proposal with us before you spend a lot of time writing code. Even when your proposal gets validated by the community, we still recommend doing the actual work as a series of small, self-contained commits. This makes the reviewer's job much easier and increases the timeliness of feedback. - -When it comes to C and C++ parts of IvorySQL, we follow PostgreSQL Coding Conventions. In addition to that: - -For C and Perl code, please run pgindent if necessary. We recommend using git diff --color when reviewing your changes so that you don't have any spurious whitespace issues in the code that you submit. - -All new functionality that is contributed to IvorySQL should be covered by regression tests that are contributed alongside it. If you are uncertain about how to test or document your work, please raise the question on the ivorysql-hackers mailing list and the developer community will do its best to help you. - -At the very minimum, you should always be running make installcheck-world to make sure that you're not breaking anything. - -==== Changes applicable to upstream PostgreSQL - -If the change you're working on touches functionality that is common between PostgreSQL and IvorySQL, you may be asked to forward-port it to PostgreSQL. This is not only so that we keep reducing the delta between the two projects, but also so that any change that is relevant to PostgreSQL can benefit from a much broader review of the upstream PostgreSQL community. In general, it is a good idea to keep both codebases handy so you can be sure whether your changes may need to be forward-ported. - -==== Patch submission - -Once you are ready to share your work with the IvorySQL core team and the rest of the IvorySQL community, you should first create or claim the corresponding GitHub Issue, then push all the commits to a branch in your own repository forked from the official IvorySQL and send us a pull request. Every pull request must correspond to at least one Issue so that the change request, discussion, review, and merge result remain traceable. - -==== Patch review - -A submitted pull request with passing validation checks is assumed to be available for peer review. Peer review is the process that ensures that contributions to IvorySQL are of high quality and align well with the road map and community expectations. Every member of the IvorySQL community is encouraged to review pull requests and provide feedback. Since you don't have to be a core team member to be able to do that, we recommend following a stream of pull reviews to anybody who's interested in becoming a long-term contributor to IvorySQL. - -One outcome of the peer review could be a consensus that you need to modify your pull request in certain ways. GitHub allows you to push additional commits into a branch from which a pull request was sent. Those additional commits will be then visible to all of the reviewers. - -A peer review converges when it receives at least one +1 and no -1s votes from the participants. At that point, you should expect one of the core team members to pull your changes into the project. - -At any time during the patch review, you may experience delays based on the availability of reviewers and core team members. Please be patient. That being said, don't get discouraged either. If you're not getting expected feedback for a few days add a comment asking for updates on the pull request itself or send an email to the mailing list. - -==== Direct commits to the repository - -On occasion, you will see core team members committing directly to the repository without going through the pull request workflow. This is reserved for small changes only and the rule of thumb we use is this: if the change touches any functionality that may result in a test failure, then it has to go through a pull request workflow. If, on the other hand, the change is in the non-functional part of the codebase (such as fixing a typo inside of a comment block) core team members can decide to just commit to the repository directly. - -== **Submit Issue** - -=== First: Get into New issue page: - -1 Enter IvorySQL official website:https://github.com/IvorySQL/IvorySQL - -2 Click New issue - -image::p3.png[] - -==== Second:Select the issue type - -**1 bug report** - -``` -Title: -``` - -``` -## Bug Report -Describe the bug - - -\### IvorySQL Version -The version of IvorySQL you are using - -\### OS Version (uname -a) -Operating system version(uname -a) - -\### Configuration options ( config.status --config ) - - -\### Current Behavior - - -\### Expected behavior/code - - -\### Step to reproduce - - -\### Additional context that can be helpful for identifying the problem - -``` - - - -**2 Enhancement** - -``` -Title: -``` - -``` -## Enhancement -Describe the functions that you expect to be strengthened -``` - - - -**3 Feature Request** - -``` -Title: -``` - -``` -## Feature Request -Describe the feature that you expect to be real -``` - -==== Third: Submit - -Click submit new issue button. WELL DONE! - -== **Contribute Code** - -=== First: Fork https://ivorysql.org/[ivorysql.org] warehouse - -1 Open the ivorysql warehouse: https://github.com/IvorySQL/IvorySQL - -2 Click the fork button in the upper right corner, Wait for the fork to finish - -Before you start coding or editing documents, make sure there is a corresponding GitHub Issue for the change. You can create a new Issue or claim an existing one, but do not submit a PR without an associated Issue. - -=== Second: Clone the warehouse to local - -``` -cd $working_dir # $working_dir can be replaced by the directory where you want to place repo. For example, `cd ~/Documents/GitHub` - -git clone git@github.com:$user/IvorySQL.git # `$user` can be replaced by your GitHub ID. -``` - -=== Third: Create a new Branch - -``` -cd $working_dir/IvorySQL - -git checkout -b new-branch-name -``` - -=== Fourth: Edit Document or Modify Code - -You can modify the code in new-branch-name. - -=== Fifth: Generate commit - -``` -Git add - -Git commit -m “commit-message” -``` - -=== Sixth: Push the modification to the remote end - -``` -Git push -u origin new-branch-name -``` - -=== Seventh: Create a Pull Request - -1 Open your warehouse: https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL] ($user is your GitHub ID) . - -2 Click Compare & pull request button and create a PR. - -3 In the PR title or description, explicitly reference the corresponding Issue number, for example `Fixes #123` or `Refs #123`. - -== **Submit PR** - -A PR submission should contain only one function or one bug. Prohibit submitting multiple functions at one time. - -Every GitHub PR must have a corresponding Issue. A PR without an associated Issue does not meet the community contribution process requirements. - -=== Fill in PR information - -``` -Fix test -Describe the function -``` - -``` -leave a comment -Give a detailed description of the submission function -``` - -Reference the related Issue in the PR description and keep the Issue number visible to reviewers, for example `Fixes #123`. - -=== Submit PR - -Click Create pull request button. WELL DONE! - -== **Edit Documents** - -=== Preparation - -(1) Download Markdown or Typora document editor. - -(2) Check whether the source warehouse has updates. If there are updates, please update and synchronize to your own warehouse first. Refer to the following steps to update to the latest version: - -``` -git remote - -git fetch upstream - -git merge upstream/main - -git push -``` - -(3) Familiar with format <<#_pecification>>. - -=== Where to Contribute - -The IvorySQL community provides Chinese and English documents. English documents are saved in IvorySQL document repository, Chinese documents are saved in i18n document repository. You can contribute to one of them or both. - -You can start from any of following to help improve the IvorySQL documents on the IvorySQL website: - -​ (1) Prepare complete documents. - -​ (2) Fix incorrect spelling and formatting (Punctuation, space, indentation, code block, etc) . - -​ (3) Improper or outdated instructions corrected or updated. - -​ (4) Add missing content (sentences, paragraphs, or new documents) . - -​ (5) Translate document from English to Chinese, or from Chinese to English. - -​ (6) Submit, reply and resolve document issues or document-i18n issues. - -​ (7) (Advanced) View pull requests created by others. - -=== Specification - -The IvorySQL document is written in 'markdown'. To ensure the quality and consistency of the format, certain Markdown rules should be followed when modifying and updating the document. - -**Markdown Specification** - -​ 1 Titles are used incrementally from the first level, and skipping is prohibited. For example: The third level title cannot be used directly under the first level title; The fourth level title cannot be used directly under the second level title. - -​ 2 The title must use the ATX style uniformly. Indicate the title level by adding # before the title. - -​ 3 The leading symbol # of the title must be followed by a blank space. - -​ 4 The leading symbol "#" of the title can only be followed by one blank space and then the title content. There can be no more than one space. - -​ 5 The title must appear at the beginning of a line, there must be no space before the # sign of the title. - -​ 6 Only Chinese and English question marks, back quotes, Chinese and English single and double quotes and other symbols can appear at the end of the title. Other symbols such as colon, comma, period and exclamation point cannot be used at the end of the title. - -​ 7 One line must be empty above the title. - -​ 8 The same title cannot appear continuously in the document. If the first level title is # TiDB architecture, the next level title cannot be # # TiDB architecture. If it is not a continuous title, the title content can be repeated. - -​ 9 Only one first level title in document. - -​ 10 In general, except for TOC.md files, which can be indented by two spaces, other .md files must be indented by four spaces by default foe each level of indentation. - -​ 11 Tab is not allowed in documents(including code blocks) . If indentation is required, spaces must be uniformly used instead. - -​ 12 Continuous blank lines are prohibited. - -​ 13 Multiple spaces are not allowed after the block reference symbol > . Only one space can be used, followed by the reference content. - -​ 14 When using a ordered list, it must start from 1 and increase in order. - -​ 15 When using a list, the identifier (+, -, * or number) of each list item can only be left blank, followed by the list content. - -​ 16 The list (includeing ordered and unordered lists) must be empty before and after each line. - -​ 17 There must be one blank line before and after the code block. - -​ 18 Exposed URLs are prohibited in documents. If you want users to click and open the URL directly, wrap the URL with a pair of angle brackets () . If the exposed URL must be used due to special circumstances, and the user does not need to open it by clicking, a pair of back quatation marks (`URL`) will be used to wrap the URL. - -​ 19 When using bold, italic and other emphasis effects, redundant spaces are prohibited in the emphasis identifier, such as `** text **`. - -​ 20 No extra space is allowed in the code block wrapped by a single backquote, such as ` text `. - -​ 21 No extra spaces are allowed on both sides of the link text, such as [Link](https://www.example.com/) - -​ 22 The link must have a link path. [Empty link]() and [empty link](#) are not allowed. - -=== Example - -1 Titles are used incrementally from the first level, and skipping is prohibited. - -``` -# Heading 1 -### Heading 3 - -We skipped out a 2nd level heading in this document -``` - - - -2 The title must use the ATX style uniformly. Indicate the title level by adding # before the title. -``` -# Heading 1 -## Heading 2 -### Heading 3 -#### Heading 4 -## Another Heading 2 -### Another Heading 3 -``` - - - -3 The leading symbol # of the title must be followed by a blank space. Multiple spaces after # are prohibited, and spaces before # are prohibited. - -Incorrect Example: - -``` -# Heading 1 -## Heading 2 -``` - -Correct Example: - -``` -# Heading 1 -## Heading 2 -``` - - - -4 Only Chinese and English question marks, back quotes, Chinese and English single and double quotes and other symbols can appear at the end of the title. - -Incorrect Example: - -``` -# This is a heading. -``` - -Correct Example: - -``` -# This is a heading -``` - - - -5 One line must be empty above the title. - -Incorrect Example: - -``` -# Heading 1 -Some text -Some more text## Heading 2 -``` - -Correct Example: - -``` -# Heading 1 -Some text -Some more text - -## Heading 2 -``` - - - -6 he same title cannot appear continuously in the document. If the first level title is # TiDB architecture, the next level title cannot be ## TiDB architecture. If it is not a continuous title, the title content can be repeated. - -Incorrect Example: - -``` -# Some text - -## Some text -``` - -Correct Example: - -``` -# Some text - -## Some more text -``` - - - -7 Only one first level title in document. - -Incorrect Example: - -``` -# Top level heading - -# Another top-level heading -``` - -Correct Example: - -``` -# Title - -## Heading - -## Another heading -``` - - - -8 In general, except for TOC.md files, which can be indented by two spaces, other .md files must be indented by four spaces by default foe each level of indentation. - -Incorrect Example: - -``` -* List item - * Nested list item indented by 3 spaces -``` - -Correct Example: - -``` -* List item - * Nested list item indented by 4 spaces -``` - - - -9 Tab is not allowed in documents(including code blocks) . If indentation is required, spaces must be uniformly used instead. - -Incorrect Example: - -``` -Some text - * hard tab character used to indent the list item -``` - -Correct Example: - -``` -Some text - * Spaces used to indent the list item instead -``` - - - -10 Continuous blank lines are prohibited. - -Incorrect Example: - -``` -Some text here - - -Some more text here -``` - -Correct Example: - -``` -Some text here - -Some more text here -``` - - - -11 Multiple spaces are not allowed after the block reference symbol > . Only one space can be used, followed by the reference content. - -Incorrect Example: - -``` -> This is a blockquote with bad indentation> there should only be one. -``` - -Correct Example: - -``` -> This is a blockquote with correct> indentation. -``` - - - -12 When using a ordered list, it must start from 1 and increase in order. - -Incorrect Example: - -``` -1. Do this. -1. Do that. -1. Done. -``` - -``` -0. Do this. -1. Do that. -2. Done. -``` - - Correct Example: - -``` -1. Do this. -2. Do that. -3. Done. -``` - - - -13 When using a list, the identifier (+, -, * or number) of each list item can only be left blank, followed by the list content. - -Correct Example: - -``` -* Foo -* Bar -* Baz - -1. Foo - * Bar -1. Baz -``` - - - -14 The list (includeing ordered and unordered lists) must be empty before and after each line. - -Incorrect Example: - -``` -Some text* Some* List - -1. Some2. List - -Some text -``` - -Correct Example: - -``` -Some text - -* Some -* List - -1. Some -2. List - -Some text -``` - - - -15 There must be one blank line before and after the code block. - -Incorrect Example: - -``` -Some text -​``` -Code block -​``` -​``` -Another code block -​``` -Some more text -``` - -Correct Example: - -``` -Some text - -​``` -Code block -​``` - -​``` -Another code block -​``` - -Some more text -``` - - - -16 Exposed URLs are prohibited in documents. If you want users to click and open the URL directly, wrap the URL with a pair of angle brackets () . If the exposed URL must be used due to special circumstances, and the user does not need to open it by clicking, a pair of back quatation marks (`URL`) will be used to wrap the URL. - -Incorrect Example: - -``` -For more information, see https://www.example.com/. -``` - -Correct Example: - -``` -For more information, see . -``` - - - -17 When using bold, italic and other emphasis effects, redundant spaces are prohibited in the emphasis identifier, such as `** text **`. - -Incorrect Example: - -``` -Here is some ** bold ** text. - -Here is some * italic * text. - -Here is some more __ bold __ text. - -Here is some more _ italic _ text. -``` - -Correct Example: - -``` -Here is some **bold** text. - -Here is some *italic* text. - -Here is some more __bold__ text. - -Here is some more _italic_ text. -``` - - - -18 No extra space is allowed in the code block wrapped by a single backquote, such as ` text `. - -Incorrect Example: - -``` -some text - some text -``` - -Correct Example: - -``` -some text -``` - - - -19 No extra spaces are allowed on both sides of the link text, such as [ Link ](https://www.example.com/) . -Incorrect Example: - -``` -[a link](https://www.example.com/) -``` - -Correct Example: - -``` -[a link](https://www.example.com/) -``` - - - -20 The link must have a link path. [Empty link]() and [empty link](#) are not allowed. - -Incorrect Example: - -``` -[an empty link]() - -[an empty fragment](#) -``` - -Correct Example: - -``` -[a valid link](https://example.com/) - -[a valid fragment](#fragment) -``` - - - -21 Code blocks in the document are wrapped with three backquote, and the use of indented four-space code blocks is prohibited. - -Incorrect Example: - -``` -Some text. - - # Indented code - -More text. -``` - -Correct Example: - -``` -​```ruby -# Fenced code -​``` - -More text. -``` - -=== Environmental preparation - -In order to test your modifications, you need to prepare the following environment. - -* `Node.js` install -* `Antora` install - -Please refer to https://docs.antora.org/antora/latest/[Antora docs]。 - -After installation, the following display on the terminal indicates successful installation. - -image::14.png[] - -=== Generate web pages - -* Firstly, you need to know the location of the corresponding UI for the webpage, as shown in the following figure: - -image::15.png[] - -The UI templates for both Chinese and English web pages are basically the same, so when making modifications, it is best to ensure that both templates are modified at the same time. After uploading the modified UI to your personal Github, you can consider generating your modified web page locally. - -IvorySQL Document Site is built by `Antora`. Before running `Antora`, remember to modify the corresponding `playbook.yml` file. - -image::16.png[] -image::17.png[] - -After completing the above process, please run the command `antora antora-playbook.yml --stacktrace` on the terminal, and then patiently wait. After the successful operation is completed, you can view the webpage you have generated. - -You can start uploading to our *ivorysql_web*, the process of submitting PR is the same as before. Thank you for your contribution to the community ^_^. We will consider whether to update the website after the review. - -== Submit Blog - -=== Preparation - -1 Download https://markdown.com.cn/tools.html#%E7%BC%96%E8%BE%91%E5%99%A8[Markdown] or https://typoraio.cn/[Typora] . - -2 Check whether the source warehouse (https://github.com/IvorySQL/Ivory-www) has updates. If there are updates, please update and synchronize to your own warehouse first. Refer to the following steps to update to the latest version: - -``` bash -# Download source code -git clone https://github.com/IvorySQL/Ivory-www.git -# Synchronize updates warehouse -git pull -``` - -3 Familiar with format (<<#_specification_2>>) - -=== Where to Congtribute - -The IvorySQL community provides Chinese and English documents. English documents are saved in IvorySQL document repository, Chinese documents are saved in i18n document repository. You can contribute to one of them or both. - -=== How to Contribute - -Let's take a quick look at the information about the maintenance of the IvorySQL blog before contributing. It is helpful for you to submit blog and to be a contributor. - -(1) Clone code to local warehouse - -``` bash -git clone https://github.com/IvorySQL/Ivory-www.git -``` - -(2) Create a branch - -```bash -git checkout -b -``` - -(3) Create a directory of your own articles in the blog directory, and please name your own directory according to the ([Specification](#7.4 Specification) ) . - -```bash -# Make English blog directory and files -cd Ivory-www/blog -mkdir -cd -touch index.md -# Make Chinese blog directory and files -cd Ivory-www/i18n/zh-CN/docusaurus-plugin-content-blog -mkdir -cd -touch index.md -``` - -(4) Write the blog to publish in index.md, put the required pictures in the blog in the same directory as index.md. - -(5) Submit Blog - -```bash -git add -git commit -m "" -git push origin : -``` - -=== Specification - -==== Submit specifications - -(1) Format of folder naming: **year-month-day-foldername** - - Example: 2022-1-28-ivorysql-arrived - -(2) File property is **index.md** - -(3) Picture property is **.png**, and put the pictures to be uploaded into the folder to be submitted in advance. - -**Notice:**The name of every picture is unique and cannot be repeated. - -Example: po-one.png - -==== Write blog - -Blogs are written in markdown or Typora, you can understand the design of blog by reading https://docusaurus.io/zh-CN/docs/blog[Blog | Docusaurus]. - -(1) The header of blog includes the following information: - -```vim ---- -slug: IvorySQL -title: Welcome to IvorySQL community -authors: [official] -authorTwitter: IvorySql -tags: [IvorySQL, Welcome, Database, Join Us] ---- -``` - -**Prompt:**You can copy the above template to your file and edit it. - -**Notice:**1) Add one space after slug, title, authors, tags. - -2) The name of every slug is unique, the Chinese and English versions of the same blog can be the same. - -(2) Text format - -The text paragraph title is **h2**/"**Second level title**"; - -The body uses the default font size. - -(3) Naming format of inserted pictures - -[Hello](Hello-banner.png) - -(4) Naming format of inserted hyperlink - -[name](link) - -https://github.com/IvorySQL/[Github page] Download source code and published packages. - -== Website Contribution Guide - -https://docs.ivorysql.org[IvorySQL Document Site] uses https://antora.org/[`Antora`] to build. Also, IvorySQL Document Site is open source. It consists of three parts, such as https://github.com/IvorySQL/ivorysql_docs[`ivorysql_docs`], https://github.com/IvorySQL/ivorysql_web[`ivorysql_web`] and https://github.com/IvorySQL/ivory-doc-builder[`ivory-doc-builder`]. - -Welcome everyone who is willing to participate in open source work to join us, and remember to follow our code of conduct ^_^. - -=== How to Contribute - -Due to the fact that IvorySQL Document Site is all hosted on Github, this allows any users to `fork` our document repository into their personal repository, make modifications to it, and then submit a PR. After being reviewed by our open source team, the modifications can be updated to our Document Site. - -In order to achieve the goat of correcting document errors more conveniently, you first need to establish a personal warehouse according to the size you want to update. As follows: - -* If you want to modify the existing content or add a new page, you only need to `fork` https://github.com/IvorySQL/ivorysql_docs[ivorysql_docs] to your personal repository. - -image::7.png[] - -* If you want to participate more deeply in the construction of IvorySQL Document Site, in addition to the `ivorysql_docs`, you also need to `fork` https://github.com/IvorySQL/ivorysql_web[ivorysql_web] and https://github.com/IvorySQL/ivory-doc-builder[ivory-doc-builder] to your personal repository. - -image::8.png[] -image::9.png[] - -=== Modify Content - -This section will introduce the process of modifying webpage content after discovering that it is inappropriate. - -* In the upper right corner of a webpage with incorrect content, there is a button called `edit this page`, click on the button. As shown in the figure: - -image::10.png[] - -* After clicking, it will redirect to the editing page where we store the current page source `.adoc` file. Please modify the content in the `Asciidoc` format. As shown in the figure: - -image::11.png[] - -* After editing is completed. As shown in the figure: - -image::12.png[] - -* After confirming the update. As shown in the figure: - -image::13.png[] - -* Next, the relevant person of the open source team will be responsible for reviewing the content you submitted. After the review is completed, the updates you submitted will appear on the corresponding page. - -=== Add Page - -This section will introduce how to add new page components to a website, and the modifications involved in adding new pages mainly include the following: - -* Add the `.adoc` file in the `CN/modules/ROOT/pages/vX.X`. -* Modify the `CN/modules/ROOT/nav.adoc`. If the modification involves modifying or adding images, please modify the images in `images`. -* Add the `.adoc` file in the `EN/modules/ROOT/pages/vX.X`. -* Modify the `EN/modules/ROOT/nav.adoc`. If the modification involves modifying or adding images, please modify the images in `images`. - -1. Firstly, you need to download the warehouse that you `fork` from `IvorySQL` to your personal computer. - - git clone https://github.com/$username$/ivorysql_docs.git - -2. Then, place the `.adoc` file to be added in the correct directory, remembering that both Chinese and English files should be prepared (*Chinese and English files should have the same name*), and each file should be placed in the correct directory. At the same time, modify the corresponding `nav.adoc` file (the modification method can refer to the existing content of the file). -3. After the above modifications are completed, submit them to the personal warehouse first. - - git add . - git commit -m "$describe your change$" - git push - -4. Afterwards, submit the PR as follows - -image::13.png[] - -=== Test - -If you are not satisfied with simply submitting on the webpage or only modifying the webpage content, or if you want to modify the webpage UI, this section will help you. - -Before reading this section, you need to confirm whether your Github personal repository has `forked` https://github.com/IvorySQL/ivorysql_docs[ivorysql_docs], https://github.com/IvorySQL/ivorysql_web[ivorysql_web] and https://github.com/IvorySQL/ivory-doc-builder[ivory-doc-builder]. - - -=== Deploy web pages - -The deployment of web pages is currently the responsibility of the open-source team. We value every submission and issue, so please do not worry about your contribution to the community being buried. - -=== Tip - -If you don't have much time, you can send an email to **ivorysql-docs@ivorysql.org**. We will have dedicated staff to handle every your letter, and we looking forward to hearing from you. diff --git a/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc similarity index 53% rename from EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc rename to EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 9ea4d2d..9eaf902 100644 --- a/EN/modules/ROOT/pages/master/contribution/ecosystem_contribution_guide.adoc +++ b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -1,15 +1,228 @@ :sectnums: :sectnumlevels: 5 -= Ecosystem Component Adaptation Contribution Guide +:imagesdir: ./_images -== Overview += IvorySQL Contribution Guide -As an Oracle-compatible database built on PostgreSQL, IvorySQL naturally inherits PostgreSQL's rich extension ecosystem. To enable more PostgreSQL ecosystem components to run stably on IvorySQL, the IvorySQL community welcomes external contributors to participate in ecosystem component adaptation work. +IvorySQL grows through contributions from developers, testers, documentation writers, translators, community advocates, and users around the world. This guide will help you understand how to participate in the IvorySQL community, from getting started to making in-depth contributions. + +== Ways to Contribute + +The IvorySQL community believes that open source should be approachable and that no contribution is too small. You can participate in a way that matches your background and interests: + +* *Code contributions*: kernel development, feature iteration, bug fixes, plugin development, ecosystem tool adaptation, regression tests, and code review. +* *Non-code contributions*: issue reports, documentation improvements, technical translation, community Q&A, online or offline talks, case studies, migration experience sharing, and community promotion. + +If you are not ready to submit code yet, you can still make a meaningful contribution by reproducing issues, clarifying requirements, improving docs, or helping other users in community discussions. + +== Incentive Policy + +To encourage long-term participation, the IvorySQL community continues to improve how contributors are recognized and supported: + +* *Recognition*: contributors may receive community digital certificates and be featured on the official https://www.ivorysql.org/contributors[contributor wall] to record their open-source footprint. +* *Mentorship*: the "Lighthouse" mentoring model helps contributors grow with technical guidance, one-on-one support, and code review feedback from experienced community members. +* *Community opportunities*: active contributors may receive speaking, sharing, or participation opportunities at community events such as HOW and other technical activities. +* *Annual incentives*: the community may select outstanding contributors for merchandise, public recognition, ecosystem exposure, and other collaboration opportunities. + +Specific arrangements may evolve with community programs, but sustained and valuable contributions are always taken seriously and recognized. + +If you are interested in code contributions but are not sure where to start, or if this is your first time contributing to IvorySQL, the guide below is meant to help you find a clear entry point and lower the barrier to participation. + +== Community Collaboration Process + +The IvorySQL community employs a closed-loop open-source collaboration process, ensuring that every step—from issue submission to version release—receives closed feedback and continuous improvement. This process encourages良性互动 between users and developers, allowing community development to evolve around actual needs. + +The entire closed-loop collaboration process is as follows: + +🐛 *Submit Issue* + +Users or developers submit bugs, feature suggestions, or usage feedback on the GitHub Issues page. + +💬 *Discussion* + +Maintainers and community members discuss the issue, confirm its nature and priority, and add it to the ToDo List. + +🛠️ *Development Branch (Fork & Dev)* + +Developers claim the Issue, fork the repository, develop and test locally, and prepare to submit code. + +🚀 *Submit Pull Request (PR)* + +Push the development branch to the forked repository and initiate a merge request to the upstream repository. + +🧐 *Code Review* + +Maintainers or core developers review the PR, provide modification suggestions, and ensure quality. + +🔀 *Merge to Main Branch* + +After approval, the PR is merged into the main branch, and the corresponding Issue is closed. + +📦 *Release* + +The project regularly releases new versions (minor versions quarterly, major versions annually), including the latest fixes and features. + +🧪 *User Testing* + +Users upgrade to the new version, provide feedback on new issues, and new Issues are generated, forming a complete feedback loop. + +image::p23.jpg[] + +Through this complete closed-loop collaboration mechanism, IvorySQL achieves full-process closure of issue response → development contribution → quality assurance → release feedback, promoting the continuous healthy evolution of the project. + +📢 Please read and abide by our https://github.com/IvorySQL/IvorySQL/blob/master/CODE_OF_CONDUCT_CN.md[IvorySQL Community Code of Conduct]. + +== Roles and Responsibilities + +Before contributing, please confirm your current participation role to more efficiently understand the contribution methods suitable for you: + +=== Users + +As a user, you play an important role in using IvorySQL. We encourage you to: + +==== Provide Feedback and Requirements + +* Found a bug, performance issue, or inaccurate documentation? +* Have new feature suggestions or usage experience improvements? + +If you are preparing to report a bug or submit requirements to the community, please submit an Issue in the corresponding IvorySQL community repository and refer to the Issue xref:master/contribution/issue_submission_guide.adoc[Submission Guide]. + +==== Participate in Community Discussions + +* Discuss through the https://lists.ivorysql.org[mailing list] +* Join https://github.com/IvorySQL/IvorySQL/discussions[GitHub Discussions] to supplement information or verify issues +* Participate in technical discussions in WeChat, Discord, and other chat groups + +=== Contributors + +We welcome all types of contributions including code, documentation, and testing. + +==== Find Projects You're Interested In + +We divide the repository into multiple sub-projects. You can find projects of interest and their code repositories from the following list: + +[cols="1,1"] +|=== +|Repository | Description + +|https://github.com/IvorySQL/IvorySQL[IvorySQL] | Responsible for the development and maintenance of the IvorySQL database +|https://github.com/IvorySQL/Ivory-www[Ivory-www] | Responsible for the development and maintenance of the community website +|https://github.com/IvorySQL/ivory-operator[ivory-operator] | Responsible for the development and maintenance of IvorySQL cloud-native database and peripheral tools +|https://github.com/IvorySQL/docker_library[docker_library] | Responsible for the construction and maintenance of IvorySQL multi-architecture images +|https://github.com/IvorySQL/ivory-cloud[ivory-cloud] | Responsible for the development and maintenance of IvorySQL cloud service platform and peripheral ecosystem +|https://github.com/IvorySQL/ivorysql_docs[Ivorysql_docs] | Responsible for the development and maintenance of the community documentation center +|https://github.com/IvorySQL/ivory-doc-builder[ivory-doc-builder] | Responsible for compiling Ivorysql_docs +|https://github.com/IvorySQL/ivorysql_web[Ivorysql_web] | Responsible for the maintenance of the community documentation website +|https://github.com/IvorySQL/ivorysql-wasm[Ivorysql_wasm] | Responsible for the development and maintenance of the IvorySQL online experience website +|=== + +==== Assign Issues to Yourself + +You can assign Issues you created or Issues you are willing to handle to yourself. Simply enter `/assign` in the comment box, and the bot will assign the issue to you. There may already be communication and discussion among participants under each Issue. If you are interested, you can also express your opinions in the comment box to participate in Issue discussions. + +=== Maintainers + +Maintainers are responsible for managing IvorySQL code, PR reviews, leading version releases, and IvorySQL development direction. + +==== Community Planning + +* Develop version planning and Roadmap +* Track and evaluate community needs +* Maintain a public TODO list + +==== Code Management + +* Participate in Pull Request reviews +* Review security issues to ensure project health + +==== Process and Governance Mechanisms + +* Optimize collaboration mechanisms (code contribution guides, PR templates, etc.) +* Establish vulnerability response mechanisms and codes of conduct + +== Getting Started + +=== Register a GitHub Account + +Whether you want to submit Issues, participate in discussions, or contribute code and documentation, you need to log in with a GitHub account and interact with the IvorySQL project. + +Please refer to to register your GitHub account and familiarize yourself with Git tools and workflows. + +IvorySQL source code is hosted on GitHub: . + +=== Sign the CLA + +Before submitting code or documentation contributions, individual or corporate contributors need to sign the Contributor License Agreement (CLA) to ensure code legality and compliance. Signing the CLA is a necessary condition for the IvorySQL community to accept contributions, ensuring your contributions are legally distributed. Please download the CLA according to the following links, sign it, and send the signed CLA to cla@ivorysql.org. + +* https://www.ivorysql.org/zh-CN/assets/files/individual_cla-a81f001209eb5ce0f8ea7c3be4cc69b5.pdf[Individual Contributor] +* https://www.ivorysql.org/zh-CN/assets/files/corporate_cla-76e89b6f17b0bc102cbc1105d438a917.pdf[Corporate Contributor] + +Pull requests from contributors who have not signed the CLA cannot proceed to formal review. + +== Code Contributions + +=== Environment Preparation + +IvorySQL development and collaboration happen on GitHub. Before contributing, it is recommended that you: -This document provides complete guidance for contributors who want to participate in ecosystem component adaptation, covering the entire process from topic selection, environment preparation, adaptation testing, documentation writing, to contribution submission. +* Have a GitHub account and be familiar with basic Git workflows +* Fork the official repository and work on a dedicated branch in your own fork +* Follow community discussions or mailing lists when relevant, especially for larger proposals -== Adaptation Scope +=== Patch Submission + +We recommend the following contribution flow: + +. Choose an entry point from GitHub issues, documentation gaps, community activities, or ecosystem needs. +. For larger changes, discuss the proposal first in an issue, pull request thread, or mailing list to reduce rework. +. Fork the repository and create a focused branch for one self-contained change. +. Complete the implementation, tests, or documentation updates and review your own changes locally. +. Submit a pull request to the official repository, or use issues and discussions for non-code contributions. +. Respond to review feedback, push follow-up commits when needed, and iterate until the change is ready to merge. + +=== Coding and Testing Guidelines + +To improve review quality and merge efficiency, we recommend the following: + +* Split larger ideas into a series of small, self-contained commits whenever possible. +* Follow PostgreSQL coding conventions for C and C++ related changes. +* Run `pgindent` for C and Perl code when needed. +* Use `git diff --color` before submission to catch accidental whitespace-only changes. +* Add regression tests for new functionality whenever possible. +* At minimum, run `make installcheck-world` to ensure your changes do not introduce obvious regressions. + +If you are unsure how to test or document a change, ask on the `ivorysql-hackers` mailing list and the community will do its best to help. + +=== Licensing of Contributions + +If the contribution you are submitting is original work, you can assume it will be released as part of IvorySQL under the Apache License, Version 2.0. + +If the contribution is not original work, you must clearly indicate the original license and ensure it is compatible with Apache License 2.0 terms. Proper attribution may also be required. In general, never remove an existing license header from third-party or previously licensed work unless you are absolutely certain it is appropriate to do so. + +If you are unsure about the licensing implications of your contribution, please contact the community before submitting it. + +=== Changes Applicable to PostgreSQL Upstream + +If your change touches functionality shared by PostgreSQL and IvorySQL, the community may ask you to forward-port or propose the change upstream. This helps reduce long-term divergence between the two projects and gives broadly useful changes access to wider review in the PostgreSQL ecosystem. + +=== Patch Review + +A submitted pull request with passing checks is considered available for peer review. Review feedback helps ensure that changes are aligned with project quality standards, roadmap direction, and community expectations. + +Possible review outcomes include requests for additional commits, changes in scope, testing improvements, or documentation updates. Please do not be discouraged by iteration; it is a normal part of open-source collaboration. + +When feedback is delayed, it is fine to leave a polite comment on the pull request or ask for an update through the community channels. + +=== Direct Commits + +Small non-functional fixes may occasionally be committed directly by core team members. Changes that affect behavior, testing, or product functionality should go through the pull request workflow. + +== Ecosystem Component Adaptation + +As an Oracle-compatible database built on PostgreSQL, IvorySQL naturally inherits PostgreSQL's rich extension ecosystem. To enable more PostgreSQL ecosystem components to run stably on IvorySQL, the IvorySQL community welcomes external contributors to participate in ecosystem component adaptation work. + +=== Adaptation Scope The following types of components are welcome for adaptation contributions: @@ -17,19 +230,19 @@ The following types of components are welcome for adaptation contributions: * Third-party plugins developed based on PostgreSQL's extension mechanism * Peripheral ecosystem tools that work alongside the database as independent processes, such as connection pools, proxies, and middleware -== Contribution Process +=== Contribution Process Ecosystem component adaptation is the work of adapting PostgreSQL ecosystem components to run on IvorySQL. The main activities include: understanding the target component's characteristics, principles, and usage; testing whether it works correctly under IvorySQL's PG mode and Oracle compatibility mode; and finally, based on the above research and testing, writing an ecosystem component adaptation document and submitting it to the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository. After the document is submitted, maintainers will reproduce the test of the target component following the steps given in the adaptation document; once they confirm the test results are consistent with the document, they will merge the PR. For the specific steps of topic selection, testing, and documentation writing, please refer to the detailed steps below. -=== Step 1: Topic Selection and Communication +==== Step 1: Topic Selection and Communication -==== Confirm the Component Is Not Yet Adapted +===== Confirm the Component Is Not Yet Adapted Before starting adaptation work, please check the xref:master/ecosystem_components/ecosystem_overview.adoc[Ecosystem Component Adaptation List] to confirm whether the target component has already been adapted. If the target component is not in the list, continue with the following process; otherwise, please choose another unadapted component. -==== Claim or Create an Issue +===== Claim or Create an Issue Search for the target component in the https://github.com/IvorySQL/IvorySQL/issues[Issue list] of the IvorySQL repository: @@ -41,13 +254,13 @@ Maintainers will evaluate whether the component is suitable for inclusion in the [TIP] It is recommended to start adaptation work only after receiving confirmation from maintainers to avoid duplicate or unnecessary work. -==== Sign the CLA +===== Sign the CLA -Before submitting documentation contributions, please ensure you have signed the Contributor License Agreement (CLA). For details, please refer to the CLA signing instructions in the xref:master/contribution/community_contribution_guide.adoc[Community Contribution Guide]. +Before submitting documentation contributions, please ensure you have signed the Contributor License Agreement (CLA). For details, please refer to the xref:#_sign_the_cla[Sign the CLA] section of this guide. -=== Step 2: Environment Preparation +==== Step 2: Environment Preparation -==== IvorySQL Environment +===== IvorySQL Environment Please prepare an IvorySQL environment for testing, preferably meeting the following requirements: @@ -58,7 +271,7 @@ Please prepare an IvorySQL environment for testing, preferably meeting the follo [TIP] You can quickly set up a test environment using IvorySQL's official Docker images. Refer to xref:master/containerization/docker_podman_deployment.adoc[Docker & Podman Deployment]. -==== Build Toolchain +===== Build Toolchain Prepare the appropriate toolchain based on the target component's build method: @@ -66,18 +279,18 @@ Prepare the appropriate toolchain based on the target component's build method: * Rust extensions: cargo, rustc, and other Rust toolchain components * Extensions in other languages: corresponding language runtime environments -=== Step 3: Adaptation Testing +==== Step 3: Adaptation Testing The goals of ecosystem component adaptation are divided into two levels: - PG mode: the component must be fully usable. - Oracle compatibility mode: it should be fully usable if possible; if it cannot be fully usable, at least the core functionality should work normally. For PG-specific extensions whose underlying mechanisms fundamentally conflict with Oracle compatibility mode and cannot run in this mode at all (for example, pg_partman, which is designed specifically to manage PostgreSQL partitioned tables and does not support running in Oracle compatibility mode), you must explain the situation in the adaptation document and the PR description. -==== Compile and Install the Component +===== Compile and Install the Component Please refer to the target component's official documentation for compilation and installation. -==== Test PG Mode +===== Test PG Mode Start an IvorySQL instance, connect to the database with psql through port 5432, and perform the following verifications: @@ -98,7 +311,7 @@ Hook-type components loaded via `shared_preload_libraries` do not need this step If a certain function cannot be used or a test fails, investigate the cause: if it is an IvorySQL-side issue, open a PR against the IvorySQL repository to fix it; if it is a component-side issue, report it to the component's repository and record the limitation in the adaptation document. -==== Test Oracle Compatibility Mode +===== Test Oracle Compatibility Mode Connect to the database with psql through port 1521 (the Oracle compatibility port) and perform the following verifications: @@ -118,7 +331,7 @@ Record whether each function is available in Oracle compatibility mode; this ser [NOTE] Not all components can work in Oracle compatibility mode. If running `CREATE EXTENSION` or calling a component function fails due to a syntax error, it is usually because the component internally uses PG-specific syntax that Oracle does not support; please refer to the PG syntax whitelist mechanism in the next section to fix it. If the component fundamentally conflicts with Oracle compatibility mode at the underlying-mechanism level (such as pg_partman), you must clearly state this in the adaptation document and the PR description. -==== Fix Compatibility Issues via the PG Syntax Whitelist +===== Fix Compatibility Issues via the PG Syntax Whitelist A common reason why Oracle compatibility mode testing fails — especially when `CREATE EXTENSION` fails outright — is that the extension is implemented through SQL scripts that make heavy use of PG-specific syntax that Oracle does not support (such as PG-style `interval` expressions and array slicing), so the scripts cannot pass syntax parsing under Oracle compatibility mode. @@ -141,7 +354,7 @@ This approach does not apply to: Once you confirm that the target extension falls into the applicable scenario, you can open a PR against the IvorySQL repository to add the extension name to the `PgDialectExtensions` whitelist, and attach the test results from both modes in the PR description; at the same time, state in the "Oracle Compatibility" section of the adaptation document that the extension runs through the whitelist mechanism. -=== Step 4: Documentation Writing +==== Step 4: Documentation Writing ==== Document Structure @@ -247,9 +460,9 @@ After completing the component documentation, please make sure to update the plu [NOTE] Both the Chinese and English versions of the overview page need to be updated. -=== Step 5: Submit PR +==== Step 5: Submit PR -==== Create Branch +===== Create Branch Ecosystem component adaptation documents are submitted to the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository (note: this is not the IvorySQL main repository where you create Issues). Please first fork the repository and clone it locally, then create a feature branch: @@ -258,14 +471,14 @@ Ecosystem component adaptation documents are submitted to the https://github.com git checkout -b feature/adapt- ---- -==== Add Files +===== Add Files -. Place the documentation file in the `CN/modules/ROOT/pages/master/ecosystem_components/` directory -. If there are image resources, place them in the `CN/modules/ROOT/images/` directory -. Prepare the English version simultaneously and place it in the corresponding EN directory +. Place the documentation file in the `EN/modules/ROOT/pages/master/ecosystem_components/` directory +. If there are image resources, place them in the `EN/modules/ROOT/images/` directory +. Prepare the Chinese version simultaneously and place it in the corresponding CN directory . Update the links in both the CN and EN `nav.adoc` and `ecosystem_overview.adoc` -==== Create PR +===== Create PR . Open a PR against the `master` branch of the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository. . Use `Fixes IvorySQL/IvorySQL#` in the PR description to link the adaptation Issue you claimed or created in Step 1 @@ -281,20 +494,20 @@ git checkout -b feature/adapt- . The linking keyword must be written in the PR description submitted to the IvorySQL docs repository and spelled correctly (`Fixes`/`Closes`/`Resolves` + a space + `IvorySQL/IvorySQL#`); writing it in a comment has no effect. ==== -==== Await Review +===== Await Review Maintainers will reproduce the test following the steps in the document and review the PR. They may suggest the following modifications: * Add missing test cases * Fix documentation format issues * Improve Oracle compatibility testing -* Add the English translation +* Add the Chinese translation Please revise and update the PR promptly based on review feedback. -== Frequently Asked Questions +=== Frequently Asked Questions -=== Compilation Error: Cannot Find pg_config +==== Compilation Error: Cannot Find pg_config Please confirm the `PG_CONFIG` environment variable is set correctly, pointing to `bin/pg_config` under the IvorySQL installation directory. You can verify with: @@ -303,7 +516,7 @@ Please confirm the `PG_CONFIG` environment variable is set correctly, pointing t $PG_CONFIG --version ---- -=== Extension Creation Fails +==== Extension Creation Fails Please check: @@ -312,11 +525,14 @@ Please check: . Whether the IvorySQL version is compatible with the PostgreSQL version required by the component . If the failure is caused by PG-specific syntax that cannot be parsed, refer to the PG syntax whitelist mechanism in Step 3. -=== Functionality Issues in Oracle Compatibility Mode +==== Functionality Issues in Oracle Compatibility Mode Some PostgreSQL extensions rely on the native PG parser and may not work correctly in Oracle compatibility mode. When encountering such issues, clearly state the limitations in the document's "Oracle Compatibility" section and provide alternative solutions if available. -=== Unsure Whether a Component Is Suitable for Adaptation +==== Unsure Whether a Component Is Suitable for Adaptation Please start a discussion in https://github.com/IvorySQL/IvorySQL/issues[Issues], describing the component's functionality and your adaptation plan. Maintainers will provide an assessment. +== Acknowledgments + +Thank you to every developer, documentation editor, tester, and user who participates in IvorySQL. It is because of your efforts that IvorySQL can continue to grow! We welcome everyone to participate in IvorySQL community contributions. Our goal is to develop an active, healthy community of contributors. From 362e9e788709a4413eecb6aaf099f150c0c46548 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 14:12:55 +0800 Subject: [PATCH 04/10] docs: remove incentive policy from contribution guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Incentive policy content is maintained on the official website (www.ivorysql.org/contribution-guidelines). Replace the duplicated section with a link to avoid content redundancy. - Remove '激励政策' section from Chinese version - Remove 'Incentive Policy' section from English version - Add links pointing to official website for incentive details --- .../master/contribution/contribution_guide.adoc | 13 +------------ .../master/contribution/contribution_guide.adoc | 13 +------------ 2 files changed, 2 insertions(+), 24 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 3dc803b..dee68a9 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -16,18 +16,7 @@ IvorySQL 社区相信开源应当触手可及，每一份贡献都弥足珍贵 如果您还不确定如何开始，也可以通过复现问题、澄清需求、改进文档或在社区讨论中帮助其他用户来做出有意义的贡献。 -== 激励政策 - -为鼓励长期参与，IvorySQL 社区持续完善贡献者认可与支持机制： - -* *认可机制*：贡献者可获得社区数字证书，并展示在官方 https://www.ivorysql.org/contributors[贡献者墙]，记录您的开源足迹 -* *导师计划*："灯塔"导师模式，提供技术指导和一对一支持，经验丰富的社区成员将进行代码评审反馈 -* *社区机会*：活跃贡献者可获得 HOW 等技术活动的演讲、分享或参与机会 -* *年度激励*：社区将评选优秀贡献者，提供周边、公开表彰、生态曝光等合作机会 - -具体安排可能随社区项目调整，但持续且有价值的贡献始终会被认真对待和认可。 - -如果您对代码贡献感兴趣但不确定从何开始，或者这是您第一次贡献 IvorySQL，下面的指南将帮助您找到清晰的切入点。 +关于贡献者认可和激励政策的详细信息，请访问 https://www.ivorysql.org/contribution-guidelines[IvorySQL 官网贡献指南页面]。 == 社区协作流程 diff --git a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 9eaf902..fdde761 100644 --- a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -16,18 +16,7 @@ The IvorySQL community believes that open source should be approachable and that If you are not ready to submit code yet, you can still make a meaningful contribution by reproducing issues, clarifying requirements, improving docs, or helping other users in community discussions. -== Incentive Policy - -To encourage long-term participation, the IvorySQL community continues to improve how contributors are recognized and supported: - -* *Recognition*: contributors may receive community digital certificates and be featured on the official https://www.ivorysql.org/contributors[contributor wall] to record their open-source footprint. -* *Mentorship*: the "Lighthouse" mentoring model helps contributors grow with technical guidance, one-on-one support, and code review feedback from experienced community members. -* *Community opportunities*: active contributors may receive speaking, sharing, or participation opportunities at community events such as HOW and other technical activities. -* *Annual incentives*: the community may select outstanding contributors for merchandise, public recognition, ecosystem exposure, and other collaboration opportunities. - -Specific arrangements may evolve with community programs, but sustained and valuable contributions are always taken seriously and recognized. - -If you are interested in code contributions but are not sure where to start, or if this is your first time contributing to IvorySQL, the guide below is meant to help you find a clear entry point and lower the barrier to participation. +For detailed information about contributor recognition and incentive policies, please visit the https://www.ivorysql.org/contribution-guidelines[IvorySQL official website contribution guidelines page]. == Community Collaboration Process From 87c3e4b1aabd0c2c2b3cd5716d55b7b972508e48 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 14:13:56 +0800 Subject: [PATCH 05/10] docs: remove incentive policy links from contribution guide Completely remove incentive policy content from contribution guides as it is maintained on the official website only. - Remove link reference from Chinese version - Remove link reference from English version --- .../ROOT/pages/master/contribution/contribution_guide.adoc | 2 -- .../ROOT/pages/master/contribution/contribution_guide.adoc | 2 -- 2 files changed, 4 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index dee68a9..d716716 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -16,8 +16,6 @@ IvorySQL 社区相信开源应当触手可及，每一份贡献都弥足珍贵 如果您还不确定如何开始，也可以通过复现问题、澄清需求、改进文档或在社区讨论中帮助其他用户来做出有意义的贡献。 -关于贡献者认可和激励政策的详细信息，请访问 https://www.ivorysql.org/contribution-guidelines[IvorySQL 官网贡献指南页面]。 - == 社区协作流程 IvorySQL 社区采用一套闭环式开源协作流程，确保从问题提出到版本发布，每一个环节都能闭合反馈、持续改进。这一流程鼓励用户与开发者形成良性互动，让社区开发始终围绕实际需求持续演进。 diff --git a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index fdde761..d79e088 100644 --- a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -16,8 +16,6 @@ The IvorySQL community believes that open source should be approachable and that If you are not ready to submit code yet, you can still make a meaningful contribution by reproducing issues, clarifying requirements, improving docs, or helping other users in community discussions. -For detailed information about contributor recognition and incentive policies, please visit the https://www.ivorysql.org/contribution-guidelines[IvorySQL official website contribution guidelines page]. - == Community Collaboration Process The IvorySQL community employs a closed-loop open-source collaboration process, ensuring that every step—from issue submission to version release—receives closed feedback and continuous improvement. This process encourages良性互动 between users and developers, allowing community development to evolve around actual needs. From 4dfc90a036d9941441578d9bc1602181734fa1ca Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 14:31:01 +0800 Subject: [PATCH 06/10] docs: remove contribution methods and collaboration process from guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These sections will be displayed on the official website only. The documentation site contribution guide now focuses on: - Roles and responsibilities - Getting started (GitHub account, CLA) - Code contributions - Ecosystem component adaptation - Remove '贡献方式' section from Chinese version - Remove '社区协作流程' section from Chinese version - Remove 'Ways to Contribute' section from English version - Remove 'Community Collaboration Process' section from English version --- .../contribution/contribution_guide.adoc | 53 ------------------- .../contribution/contribution_guide.adoc | 53 ------------------- 2 files changed, 106 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index d716716..74ff312 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -7,59 +7,6 @@ IvorySQL 的成长离不开来自世界各地的开发者、测试人员、文档作者、翻译者、社区布道师和用户的贡献。本指南将帮助您了解如何参与 IvorySQL 社区，从入门到深入贡献的完整路径。 -== 贡献方式 - -IvorySQL 社区相信开源应当触手可及，每一份贡献都弥足珍贵。您可以根据自己的背景和兴趣选择参与方式： - -* *代码贡献*：内核开发、功能迭代、Bug 修复、插件开发、生态工具适配、回归测试、代码评审 -* *非代码贡献*：Issue 反馈、文档改进、技术翻译、社区问答、线上线下分享、案例研究、迁移经验分享、社区推广 - -如果您还不确定如何开始，也可以通过复现问题、澄清需求、改进文档或在社区讨论中帮助其他用户来做出有意义的贡献。 - -== 社区协作流程 - -IvorySQL 社区采用一套闭环式开源协作流程，确保从问题提出到版本发布，每一个环节都能闭合反馈、持续改进。这一流程鼓励用户与开发者形成良性互动，让社区开发始终围绕实际需求持续演进。 - -整个协作闭环流程如下： - -🐛 *提问题（Issue）* - -用户或开发者在 GitHub 的 Issues 页面提交 Bug、功能建议或使用反馈。 - -💬 *问题讨论（Discussion）* - -维护者与社区成员就问题展开讨论，确认问题性质与优先级，加入 ToDo List。 - -🛠️ *开发分支（Fork & Dev）* - -开发者认领 Issue，Fork 仓库并在本地开发测试，准备提交代码。 - -🚀 *提交 Pull Request（PR）* - -将开发分支 Push 到 Fork 仓库后，向上游仓库发起合并请求。 - -🧐 *代码评审（Review）* - -维护者或核心开发者对 PR 进行评审，提出修改建议并确保质量。 - -🔀 *合并主分支（Merge）* - -审核通过后，PR 被合并至主分支，对应的 Issue 被关闭。 - -📦 *版本发布（Release）* - -项目定期发布新版本（每季度小版本，每年大版本），包含最新的修复与功能。 - -🧪 *用户测试（Test）* - -用户升级使用新版，反馈新问题，新的 Issue 随之产生，形成完整的反馈循环。 - -image::p23.jpg[] - -通过这套完整的闭环协作机制，IvorySQL 实现了问题响应 → 开发贡献 → 质量保障 → 发布反馈的全流程闭合，推动项目持续健康演进。 - -📢 请务必阅读并遵守我们的 https://github.com/IvorySQL/IvorySQL/blob/master/CODE_OF_CONDUCT_CN.md[IvorySQL社区行为准则]。 - == 角色与职责 在参与贡献前，请确认您当前的参与身份，以便更高效地了解适合您的贡献方式： diff --git a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index d79e088..ef2dfea 100644 --- a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -7,59 +7,6 @@ IvorySQL grows through contributions from developers, testers, documentation writers, translators, community advocates, and users around the world. This guide will help you understand how to participate in the IvorySQL community, from getting started to making in-depth contributions. -== Ways to Contribute - -The IvorySQL community believes that open source should be approachable and that no contribution is too small. You can participate in a way that matches your background and interests: - -* *Code contributions*: kernel development, feature iteration, bug fixes, plugin development, ecosystem tool adaptation, regression tests, and code review. -* *Non-code contributions*: issue reports, documentation improvements, technical translation, community Q&A, online or offline talks, case studies, migration experience sharing, and community promotion. - -If you are not ready to submit code yet, you can still make a meaningful contribution by reproducing issues, clarifying requirements, improving docs, or helping other users in community discussions. - -== Community Collaboration Process - -The IvorySQL community employs a closed-loop open-source collaboration process, ensuring that every step—from issue submission to version release—receives closed feedback and continuous improvement. This process encourages良性互动 between users and developers, allowing community development to evolve around actual needs. - -The entire closed-loop collaboration process is as follows: - -🐛 *Submit Issue* - -Users or developers submit bugs, feature suggestions, or usage feedback on the GitHub Issues page. - -💬 *Discussion* - -Maintainers and community members discuss the issue, confirm its nature and priority, and add it to the ToDo List. - -🛠️ *Development Branch (Fork & Dev)* - -Developers claim the Issue, fork the repository, develop and test locally, and prepare to submit code. - -🚀 *Submit Pull Request (PR)* - -Push the development branch to the forked repository and initiate a merge request to the upstream repository. - -🧐 *Code Review* - -Maintainers or core developers review the PR, provide modification suggestions, and ensure quality. - -🔀 *Merge to Main Branch* - -After approval, the PR is merged into the main branch, and the corresponding Issue is closed. - -📦 *Release* - -The project regularly releases new versions (minor versions quarterly, major versions annually), including the latest fixes and features. - -🧪 *User Testing* - -Users upgrade to the new version, provide feedback on new issues, and new Issues are generated, forming a complete feedback loop. - -image::p23.jpg[] - -Through this complete closed-loop collaboration mechanism, IvorySQL achieves full-process closure of issue response → development contribution → quality assurance → release feedback, promoting the continuous healthy evolution of the project. - -📢 Please read and abide by our https://github.com/IvorySQL/IvorySQL/blob/master/CODE_OF_CONDUCT_CN.md[IvorySQL Community Code of Conduct]. - == Roles and Responsibilities Before contributing, please confirm your current participation role to more efficiently understand the contribution methods suitable for you: From d8e4b281afd5e9387e7e3e17fc976ae2eb2c3eb9 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 15:01:59 +0800 Subject: [PATCH 07/10] docs: restructure contribution guide by merging issue submission guide Consolidate contribution documentation by renaming issue_submission_guide.adoc to contribution_guide.adoc and merging content from the previous contribution_guide.adoc. Changes: - Rename issue_submission_guide.adoc to contribution_guide.adoc (CN) - Merge roles and responsibilities section from previous contribution_guide - Merge getting started section (GitHub account, CLA signing) - Add ecosystem component adaptation entry in contribution types - Add complete ecosystem component adaptation section with detailed steps - Remove duplicate contribution_guide.adoc (EN) as it will be recreated separately This creates a unified contribution guide that serves as the single entry point for all contribution-related documentation in the docs site, while the www site maintains overview and conceptual content. --- .../contribution/contribution_guide.adoc | 1028 ++++++++++++++++- .../contribution/issue_submission_guide.adoc | 1012 ---------------- .../contribution/contribution_guide.adoc | 472 -------- 3 files changed, 988 insertions(+), 1524 deletions(-) delete mode 100644 CN/modules/ROOT/pages/master/contribution/issue_submission_guide.adoc delete mode 100644 EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 74ff312..a97f3ff 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -1,11 +1,31 @@ + :sectnums: :sectnumlevels: 5 :imagesdir: ./_images += **IvorySQL社区贡献指南** + +== **概述** + +=== 说明 + +IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvorySQL主存储库的提交权限。同时，我们非常渴望从更广泛的IvorySQL社区中的成员那里获得贡献。如果您希望看到您的代码或文档更改被添加到IvorySQL并出现在将来的版本中，本节的内容介绍是您需要知道的。 + +​IvorySQL社区欢迎并赞赏所有类型的贡献，期待您的加入！ + +=== 行为准则 + +作为成员，贡献者和领导者，我们每个人都应阅读我们的 *行为准则*。我们承诺让每个人都能参与社区，成为一种无骚扰的体验，无论年龄、体型、有形或无形的残疾、种族、性特征、性别认同和表达、经验水平、教育、社会经济地位、国籍、个人外表、种族、宗教或性身份和取向如何。 -= IvorySQL 贡献指南 +​ 我们承诺以有助于建立一个开放，热情，多样化，包容和健康社区的方式采取行动和互动。 -IvorySQL 的成长离不开来自世界各地的开发者、测试人员、文档作者、翻译者、社区布道师和用户的贡献。本指南将帮助您了解如何参与 IvorySQL 社区，从入门到深入贡献的完整路径。 +=== 管理说明 + +团队是持续开放的团队，专注于IvorySQL项目的一部分。一个团队有其审查者、提交者和维护者，并拥有一个或多个存储库。团队级别的决策来自其维护者。IvorySQL开发人员的典型提升路径是从用户到审查者，然后是提交者和维护者。但获得更多的角色并不意味着你对其他社区成员拥有任何特权。IvorySQL社区中的每个人都是平等的，都有责任与其他贡献者进行建设性合作，建立一个友好的社区。这些角色是对您在IvorySQL开发中做出重大贡献的自然奖励，并为您在开发工作流中提供更多权利，以提高您的效率。同时，他们要求你承担一些额外的责任： + +​ 团队荣誉：现在您已经是团队评审员/提交者/维护者的成员，意味着您代表着项目和您的团队成员。所以，请做一个好人来捍卫球队的声誉。 + +​ 责任：提交者/维护者有权合并拉取请求，因此承担额外的责任来处理接受代码库或文档更改的后果。这包括在它导致问题时恢复或修复它，以及帮助发布经理解决发布前测试周期中发现的任何问题。 == 角色与职责 @@ -20,7 +40,7 @@ IvorySQL 的成长离不开来自世界各地的开发者、测试人员、文 * 发现 Bug、性能缺陷或文档不准确？ * 有新的功能建议或使用体验改进？ -如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考 Issue xref:master/contribution/issue_submission_guide.adoc[提交指南]。 +如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考 Issue xref:master/contribution/contribution_guide.adoc[提交指南]。 ==== 参与社区讨论 @@ -94,63 +114,994 @@ IvorySQL 源码托管在 GitHub：。 未签署 CLA 的 Pull Request 将无法进入评审阶段。 -== 代码贡献 +== **贡献者指南** + +在贡献之前，我们需要了解下IvorySQL目前的版本以及文档的版本。目前，我们维护着5.0等版本，我们的版本紧跟PG的更新步伐，贡献之前请更新至最新版本。之后我们需要细心浏览一下贡献的样式风格，熟悉代码贡献风格、提Issue样式、拉取PR标题样式、代码注释样式、文档贡献样式、文章贡献样式，这可以帮助您尽快成为IvorySQL的贡献者奥~。 + +=== 贡献前的准备 + +==== 开始 + +IvorySQL是在GitHub上开发的，任何希望对其作出贡献的人都必须拥有GitHub帐户，并熟悉Git工具和工作流。还建议您遵循开发人员的邮件列表，因为一些贡献可能会在那里产生更详细的讨论。 + +如果您有GitHub帐户，fork这个存储库至您的个人仓库中，这样您就可以拥有您的私人副本来开始hacking，并将其用作拉取请求的来源。 + +==== IvorySQL贡献的许可 + +如果您提交的贡献是原创作品，那么您可以假设IvorySQL将作为整个IvorySQL版本的一部分发布给下游用户，该版本将遵循**Apache许可证2.0版本**。 + +​ 如果您提交的内容不是原创作品，同样鼓励代码共享和尊重原作者的著作权，同样允许代码修改，再发布。***\*请注意需要满足如下条件\****： + +（1）需要给代码的用户一份Apache许可证。 + +（2）如果您修改了代码，需要在被修改的文件中说明。 + +（3）在延伸的代码中（修改和有源代码衍生的代码中）需要带有原来代码中的协议、商标、专利声明和其他原来作者规定需要包含的说明。 + +（4）如果再发布的产品中包含一个Notice文件，则在Notice文件中需要带有Apache许可证。您可以在Notice中增加自己的许可，但不可以表现为对Apache许可证构成更改。 + +​ 最后，请记住，从非原始的工作中删除许可标头从来都不是一个好主意。即使您使用的文件部分最初在顶部有许可标头，您也应该保留它。与往常一样，如果您不太确定您的贡献所涉及的许可问题，请随时在开发人员邮件列表中联系我们。 + + +=== 您可以做什么贡献 + +==== 贡献代码 + +可以将自己修改的bug、新增的功能等代码上传至个人仓库，最后提交PR请求合并至官网：https://github.com/IvorySQL/IvorySQL 。 + +==== 文档贡献 + +IvorySQL社区提供的是中英文文档。英文文档保存在...文档存储库中，中文文档保存在i18n文档存储库中。您可以为任一文档存储库做出贡献。 + +==== 生态组件适配 + +IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 + +适配工作主要包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档。详细步骤请参考 xref:#_生态组件适配_2[生态组件适配] 章节。 + +==== 测试IvorySQL和报告问题 + +GitHub: https://github.com/IvorySQL/IvorySQL + +​码云：https://gitee.com/IvorySQL/ + + +==== 参与IvorySQL网站建设 + +IvorySQL官网下载：https://github.com/IvorySQL/Ivory-www + + +==== 回答邮件列表问题 + +邮件列表位于 官网下：https://lists.ivorysql.org/ + +==== 贡献文章 + +您可以在IvorySQL-WWW代码仓库自己提交至blog贡献，也可以联系我们IvorySQL小助理发送至邮箱ivorysql@highgo.com 。 + +=== 如何做出贡献 + +==== 编码指南 + +您获得反馈和看到代码合并到项目中的机会在很大程度上取决于更改的粒度。如果您的想法发生了更大的变化，我们强烈建议您在花大量时间编写代码之前，先加入开发人员的邮件列表，并与我们分享您的建议。即使您的建议得到社区的验证，我们仍然建议您将实际工作作为一系列小型的、独立的提交来完成。这使得评审员的工作更加容易，并提高了反馈的及时性。 + +​ 当谈到IvorySQL的C和C++部分时，我们尝试遵循PostgreSQL编码约定。除此之外： + +​ 对于C和Perl代码，如果需要，请运行pgindent。我们建议在查看更改时使用git diff--color，这样您提交的代码中就不会出现任何虚假的空白问题。 + +​ 所有贡献给IvorySQL的新功能都应该有与其一起贡献的回归测试覆盖。如果您不确定如何测试或记录您的工作，请在ivorysql-hackers邮件列表中提出问题，社区的开发人员将尽力帮助您。 + +​ 至少，您应该始终运行make install check world，以确保您没有破坏任何东西。 + +==== 适用于上游PostgreSQL的更改 + +如果您正在进行的更改涉及PostgreSQL和IvorySQL之间的通用功能，则可能会要求您将其转发到PostgreSQL。这不仅是为了我们不断减少两个项目之间的差异，而且是为了让与PostgreSQL相关的任何变化都能从对上游PostgreSQL社区更广泛的审查中受益。一般来说，将这两个代码库都放在手边是个好主意，这样您就可以确定您的更改是否需要前移。 + +==== 补丁提交 + +一旦您准备好与IvorySQL核心团队和IvorySQL社区的其他成员共享您的工作，您应该将所有提交推送到从官方IvorySQL派生的您自己的存储库中，并向我们发送请求。 + +==== 补丁审查 + +假定提交的拉取请求通过验证检查，可供同行审查。同行审查是确保对IvorySQL的贡献具有高质量并与路线图和社区期望保持一致的过程。我们鼓励IvorySQL社区的每个成员审查请求并提供反馈。由于您不必成为核心团队成员就可以做到这一点，因此我们建议您向有兴趣成为IvorySQL长期贡献者的任何人提供一系列拉动式评论。 + +​ 同行评审的一个结果可能是达成共识，即您需要以某些方式修改pull请求。GitHub允许您将其他提交推送到从中发送请求的分支中。这些额外的提交将对所有审阅者可见。 + +​ 当同行评议收到参与者至少+1张+1和no-1张的选票时，同行评议会趋于一致。在这一点上，您应该期望核心团队成员之一将您的更改引入到项目中。 + +在补丁审查期间的任何时候，您都可能会因审查人员和核心团队成员的工作效率而遇到延迟。请耐心点，也不要气馁。如果您在几天内没有收到预期的反馈，请添加一条评论，要求更新pull请求本身，或者向邮件列表发送一封电子邮件。 + +==== 直接提交到存储库 + +有时，您会看到核心团队成员直接提交到存储库，而无需执行pull请求工作流。这仅适用于小的更改，我们使用的经验法则是：如果更改涉及任何可能导致测试失败的功能，那么它必须通过pull请求工作流。另一方面，如果更改发生在代码库的非功能部分（例如在注释块中修复打字错误），则核心团队成员可以决定直接提交到存储库。 + +== **提Issue** + +=== 第1步 进入New issue 页面： + +1、进入 IvorySql官网：https://github.com/IvorySQL/IvorySQL + +​2、点击New issue + +image::p3.png[] + + +=== 第2步：选择需要填写的issue类型 + +**1、bug report** + +``` +Title: 标题 +``` + +``` +## Bug Report +对bug进行描述 + + +\### IvorySQL Version +在IvorySQL哪个版本发现的问题 + +\### OS Version (uname -a) +系统版本 + +\### Configuration options ( config.status --config ) +配置参数 + +\### Current Behavior +当前的结果 + +\### Expected behavior/code +期望的结果 + +\### Step to reproduce +复现步骤 + +\### Additional context that can be helpful for identifying the problem +有助于识别问题的其它信息 +``` + + +**2、Enhancement** + +``` +Title: 标题 +``` + +``` +## Enhancement +对于期望强化的功能作一个描述 +``` + +**3、Feature Request** + +``` +Title: 标题 +``` + +``` +## Feature Request +描述你期望实现的一个功能 +``` + + +=== 第3步：提交 + +点击 submit new issue 按钮, 提交即可 + +== **贡献代码** + +=== 第1步: Fork https://ivorysql.org/[ivorysql.org]仓库 + +1、打开ivorysql仓库 https://github.com/IvorySQL/IvorySQL + +2、点击右上角fork按钮，等待fork完成 + +=== 第2步:将fork的仓库克隆至本地 + +``` +cd $working_dir # 将 $working_dir 替换为你想放置 repo 的目录。例如，`cd ~/Documents/GitHub` + +git clone git@github.com:$user/IvorySQL.git # 将 `$user` 替换为你的 GitHub ID +``` + +=== 第3步：创建一个新的Branch + +``` +cd $working_dir/IvorySQL + +git checkout -b new-branch-name +``` + +=== 第4步：编辑文档或修改代码 + +在新建的new-branch-name中修改代码。 + +=== 第5步：生成commit + +``` +Git add + +Git commit -m “commit-message” +``` + +=== 第6步：将修改推送至远端 + +``` +Git push -u origin new-branch-name +``` + +=== 第7步：创建一个Pull Request + +1、打开你 Fork 的仓库： https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL]（将 $user 替换为你的 GitHub ID）。 + +2、点击 Compare & pull request 按钮即可创建 PR。 + +== **提交PR** + +对于提交一个PR应该保持一个功能，或者一个bug提交一次。禁止多个功能一次提交。 + + +=== 第1步：创建一个Pull Request + +1、打开你 Fork 的仓库： https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL]（将 $user 替换为你的 GitHub ID）。 + +​ 2、点击 Compare & pull request 按钮 + +=== 第2步：填写PR信息 + +``` +Fix test +功能描述 +``` + +``` +leave a comment +对该提交功能进行比较详细的描述 +``` + +=== 第3步：提交PR + +点击Create pull request 按钮即可提交。 + +== **编写文档** + +=== 准备工作 + +（1）下载Markdown或者Typora文档编辑器。 + +（2）检查源仓库是否有更新，如果有更新请先更新并同步到自己的仓库。如有更新请参阅以下步骤，更新至最新版本： + +``` +git remote + +git fetch upstream + +git merge upstream/main + +git push +``` + +（3）熟悉样式风格（规范说明） + +=== 贡献地方 + +IvorySQL社区提供双语文档。英文文档保存在IvorySQL/文档存储库（文档存储库）中，中文文档保存在 IvorySQL/文档-i18n存储库（文档-i18n 存储库）中。您可以为任何一方文档做出贡献，当然您也可以为两方同时做出贡献。 + +​ 您可以从以下任何一项开始，以帮助改进IvorySQL网站（英文和 -i18n）上的 IvorySQL文档： + +​ (1) 编写完善文档 + +​ (2) 修复拼写错误或格式（标点符号、空格、缩进、代码块等） + +​ (3) 修正或更新不当或过时的说明 + +​ (4) 添加缺少的内容（句子、段落或新文档） + +​ (5) 将文档更改从英文翻译成中文，或从中文翻译成英文。 + +​ (6) 提交、回复和解决文档问题或文档-i18n问题 + +​ (7) （高级）查看其他人创建的拉取请求 + +=== 规范说明 + +IvorySQL文档是用“markdown”编写的。为确保格式的质量和一致性，在修改更新文档时应遵循某些 Markdown 规则。 + +​ **Markdown规范** + +​ 1、标题从一级开始递增使用，禁止跳级使用。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。 + +​ 2、标题必须统一使用 ATX 风格，即在标题前加 # 号来表示标题级别。 + +​ 3、标题的引导符号 # 后必须空一格再接标题内容。 + +​ 4、标题的引导符号“#”后只能空一格后再接标题内容，不能有多个空格。 + +​ 5、标题必须出现在一行行首，即标题的 # 号前不能有任何空格。 + +​ 6、标题末尾仅能出现中英文问号、反引号、中英文单双引号等符号。其余如冒号、逗号、句号、感叹号等符号均不能在标题末尾使用。 + +​ 7、标题上面须空一行。 + +​ 8、文档中不能连续出现内容重复的标题，如一级标题为 # IvorySQL 架构，紧接着的二级标题就不能是 ## IvorySQL 架构。如果不是连续的标题，则标题内容可重复。 + +​ 9、文档中只能出现一个一级标题。 + +​ 10、一般来说，除 TOC.md 文件可缩进 2 个空格外，其余所有 .md 文件每缩进一级，默认须缩进 4 个空格。 + +​ 11、文档中（包括代码块内）禁止出现 Tab 制表符，如需缩进，必须统一用空格代替 + +​ 12、禁止出现连续的空行。 + +​ 13、块引用符号 > 后禁止出现多个空格，只能使用一个空格，后接引用内容。 + +​ 14、使用有序列表时，必须从 1 开始，按顺序递增。 + +​ 15、使用列表时，每一列表项的标识符（+、-、* 或数字）后只能空一格，后接列表内容。 + +​ 16、列表（包括有序和无序列表）前后必须各空一行。 + +​ 17、代码块前后必须各空一行。 + +​ 18、文档中禁止出现裸露的 URL。如果希望用户能直接点击并打开该 URL，则使用一对尖括号 () 包裹该 URL。如果由于特殊情况必须使用裸露的 URL，不需要用户通过点击打开，则使用一对反引号 (`URL`) 包裹该 URL。 + +​ 19、使用加粗、斜体等强调效果时，在强调标识符内禁止出现多余的空格。如不能出现 `** 加粗文本 **`。 + +​ 20、单个反引号包裹的代码块内禁止出现多余的空格。如不能出现 ` 示例文本 `。 + +​ 21、链接文本两边禁止出现多余的空格。如不能出现 [某链接](https://www.example.com/)。 + +​ 22、链接必须有链接路径。如不能出现[空链接]()或[空链接](#)等情况。 + +=== 示例 + +1、标题从一级开始递增使用，禁止跳级使用。 + +``` +# Heading 1 +### Heading 3 + +We skipped out a 2nd level heading in this document +``` + + + +2、标题必须统一使用 ATX 风格，即在标题前加 # 号来表示标题级别。 + +``` +# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +## Another Heading 2 +### Another Heading 3 +``` + + + +3、标题的引导符号 # 后必须空一格再接标题内容。禁止#后多个空格，禁止#前出现空格 + +错误示范： + +``` +# Heading 1 +## Heading 2 +``` + +正确示范： + +``` +# Heading 1 +## Heading 2 +``` + + + +4、标题末尾仅能出现中英文问号、反引号、中英文单双引号等符号。 + +错误示范 + +``` +# This is a heading. +``` + +正确示范 + +``` +# This is a heading +``` + + + +5、标题上面空一行 + +错误示范 + +``` +# Heading 1 +Some text +Some more text## Heading 2 +``` + +正确示范 + +``` +# Heading 1 +Some text +Some more text + +## Heading 2 +``` + + + +6、文档中不能连续出现内容重复的标题，如一级标题为 # IvorySQL 描述，紧接着的二级标题就不能是 ## IvorySQL 描述。如果不是连续的标题，则标题内容可重复。 + +错误示范 + +``` +# Some text + +## Some text +``` + +正确示范 + +``` +# Some text + +## Some more text +``` + + + +7、文档中只能出现一个一级标题。 + +错误示范 + +``` +# Top level heading + +# Another top-level heading +``` + +正确示范 + +``` +# Title + +## Heading + +## Another heading +``` + + + +8、一般来说，除 TOC.md 文件可缩进 2 个空格外，其余所有 .md 文件每缩进一级，默认须缩进 4 个空格。 + +错误示范 + +``` +* List item + * Nested list item indented by 3 spaces +``` + +正确示范: + +``` +* List item + * Nested list item indented by 4 spaces +``` + + + +9、文档中（包括代码块内）禁止出现 Tab 制表符，如需缩进，必须统一用空格代替 + +错误示范： + +``` +Some text + * hard tab character used to indent the list item +``` + +正确示范: + +``` +Some text + * Spaces used to indent the list item instead +``` + + + +10、禁止出现连续的空行 + +错误示范 + +``` +Some text here + + +Some more text here +``` + +正确示范: + +``` +Some text here + +Some more text here +``` + + + +11、块引用符号 > 后禁止出现多个空格，只能使用一个空格，后接引用内容。 + +错误示范 + +``` +> This is a blockquote with bad indentation> there should only be one. +``` + +正确示范 + +``` +> This is a blockquote with correct> indentation. +``` + + + +12、使用有序列表时，必须从 1 开始，按顺序递增。 + +错误示范: + +``` +1. Do this. +1. Do that. +1. Done. +``` + +``` +0. Do this. +1. Do that. +2. Done. +``` + + 正确示范: + +``` +1. Do this. +2. Do that. +3. Done. +``` + + + +13、使用列表时，每一列表项的标识符（+、-、* 或数字）后只能空一格，后接列表内容。 + +正确示范 + +``` +* Foo +* Bar +* Baz + +1. Foo + * Bar +1. Baz +``` + + + +14、列表（包括有序和无序列表）前后必须各空一行。 + +错误示范 + +``` +Some text* Some* List + +1. Some2. List + +Some text +``` + +正确示范 + +``` +Some text + +* Some +* List + +1. Some +2. List + +Some text +``` + + + +15、代码块前后必须各空一行。 + +错误示范 + +``` +Some text +​``` +Code block +​``` +​``` +Another code block +​``` +Some more text +``` + +正确示范 + +``` +Some text + +​``` +Code block +​``` + +​``` +Another code block +​``` + +Some more text +``` + + + +16、文档中禁止出现裸露的 URL。如果希望用户能直接点击并打开该 URL，则使用一对尖括号 () 包裹该 URL。如果由于特殊情况必须使用裸露的 URL，不需要用户通过点击打开，则使用一对反引号 (`URL`) 包裹该 URL。 + +错误示范 + +``` +For more information, see https://www.example.com/. +``` + +正确示范 + +``` +For more information, see . +``` + + + +17、使用加粗、斜体等强调效果时，在强调标识符内禁止出现多余的空格。如不能出现 `** 加粗文本 **`。 + +错误示范 + +``` +Here is some ** bold ** text. + +Here is some * italic * text. + +Here is some more __ bold __ text. + +Here is some more _ italic _ text. +``` + +正确示范: + +``` +Here is some **bold** text. + +Here is some *italic* text. + +Here is some more __bold__ text. + +Here is some more _italic_ text. +``` + + + +18、单个反引号包裹的代码块内禁止出现多余的空格。如不能出现 ` 示例文本 `。 + +错误示范： + +``` +some text + some text +``` + +正确示范: + +``` +some text +``` + + + +19、链接文本两边禁止出现多余的空格。如不能出现 [ 某链接 ](https://www.example.com/)。 + +错误示范 + +``` +[ a link ](https://www.example.com/) +``` + +正确示范: + +``` +[a link](https://www.example.com/) +``` + + + +20、链接必须有链接路径。如不能出现[空链接]()或[空链接](#)等情况。 + +错误示范 + +``` +[an empty link]() + +[an empty fragment](#) +``` + +正确示范: + +``` +[a valid link](https://example.com/) + +[a valid fragment](#fragment) +``` + + + +21文档中的代码块统一使用三个反引号进行包裹，禁止使用缩进四格风格的代码块。 + +错误示范： + +``` +Some text. + + # Indented code + +More text. +``` + +正确示范 + +``` +```ruby +# Fenced code +​``` +More text. +``` === 环境准备 -IvorySQL 的开发和协作在 GitHub 上进行。在贡献之前，建议您： +为了测试您所做的修改是否修改，您需要准备以下环境 + +* `Node.js` 安装 +* `Antora` 安装 + +环境安装请参考 https://docs.antora.org/antora/latest/[Antora docs]。 + +安装成功后，在终端上显示如下即为成功安装。 + +image::14.png[] + + +=== 网页生成 + +通过阅读之前内容，相信您已经有了充足的准备，包括 `fork` 我们文档中心相关的三个仓库到个人仓库中，`Antora` 工具的安装准备等环境的搭建。 + +* 首先，您要知道网页对应的ui的位置，如下图： + +image::15.png[] + +中英文的网页ui模板基本一致，因此修改时应该尽量保证同时修改两个模板，将修改过后的ui再上传至个人Github上，完成了这些，就可以考虑在本地生成您修改过后的网页了。 + +文档中心是由 `Antora` 进行搭建的，在运行 `Antora` 之前，记得修改对应 `playbook.yml` 文件 + +image::16.png[] +image::17.png[] + +完成上述流程之后，请在终端运行命令 `antora antora-playbook.yml --stacktrace`，然后耐心等待，当成功运行结束后，你就可以查看自己生成的网页了。 + +在检查之后，你就可以开始着手上传至我们的 *ivorysql_web* 仓库中，提交PR的流程和之前的流程相同，感谢您对社区的贡献^_^，我们会在审核过后，考虑是否更新网站。 + +== 提交blog + +=== 准备工作 + +1、下载 https://markdown.com.cn/tools.html#%E7%BC%96%E8%BE%91%E5%99%A8[Markdown]或者 https://typoraio.cn/[Typora]文档编辑器。 + +​ 2、先下载博客源码到本地，检查源仓库(https://github.com/IvorySQL/Ivory-www)是否有更新， 如果有更新请先更新并同步到自己的仓库。请参阅以下步骤，更新至最新版本： + +``` bash +# 拉取网站源码 +git clone https://github.com/IvorySQL/Ivory-www.git +# 同步更新仓库 +git pull +``` + +​ 3、熟悉样式风格 (<<#_规范说明_2>>) + +=== 贡献地方 + +IvorySQL社区提供双语文档。英文博客保存在源码目录**Ivory-www/blog**中，中文博客保存在源码目录**Ivory-www/i18n/zh-CN/docusaurus-plugin-content-blog**中。您可以为任何一方博客做出贡献，当然您也可以为两方同时做出贡献。 + +=== 如何贡献 + +在贡献之前，让我们快速浏览一下有关IvorySQL博客维护的信息。这可以帮助您尽快成功的提交blog成为贡献者。blog提交规范 -* 拥有 GitHub 账号并熟悉基本的 Git 工作流 -* Fork 官方仓库，并在自己的 Fork 中 dedicated 分支上工作 -* 关注社区讨论或邮件列表，特别是对于较大的提案 +​ （1）将代码克隆到本地仓库 -=== 补丁提交 +``` bash +git clone https://github.com/IvorySQL/Ivory-www.git +``` -我们推荐以下贡献流程： +​ （2）创建一个分支 -. 从 GitHub Issues、文档空白、社区活动或生态需求中选择一个切入点 -. 对于较大的变更，先在 Issue、PR 讨论或邮件列表中讨论提案，减少返工 -. Fork 仓库并为一个自包含的变更创建 dedicated 分支 -. 完成实现、测试或文档更新，并在本地审查您的变更 -. 向官方仓库提交 Pull Request，或对非代码贡献使用 Issues 和 Discussions -. 响应评审反馈，必要时推送后续提交，迭代直到变更准备好合并 +```bash +git checkout -b +``` -=== 编码和测试指南 +​ （3）在博客目录中创建自己文章的目录，目录名字规则参照 (<<#_规范说明_2>>)。 -为提高评审质量和合并效率，我们建议： +```bash +# 生成英文博客目录及文件 +cd Ivory-www/blog +mkdir +cd +touch index.md +# 生成中文博客目录及文件 +cd Ivory-www/i18n/zh-CN/docusaurus-plugin-content-blog +mkdir +cd +touch index.md +``` -* 尽可能将较大的想法拆分为一系列小型、自包含的提交 -* 对于 C 和 C++ 相关变更，遵循 PostgreSQL 编码约定 -* 需要时对 C 和 Perl 代码运行 `pgindent` -* 提交前使用 `git diff --color` 检查意外的空白变更 -* 为新功能添加回归测试 -* 至少运行 `make installcheck-world` 确保您的变更没有引入明显的回归 +​ （4）在index.md编写要发布的博文，将博客中需要的图片放到和index.md同级目录。 -如果您不确定如何测试或记录变更，请在 `ivorysql-hackers` 邮件列表中提问，社区将尽力提供帮助。 +​ （5）提交发布博客 -=== 贡献的许可 +```bash +git add +git commit -m "" +git push origin : +``` -如果您提交的贡献是原创作品，您可以假设它将作为 IvorySQL 整体版本的一部分发布，该版本遵循 Apache License 2.0。 +=== 规范说明 -如果贡献不是原创作品，您必须明确指出原始许可证并确保其与 Apache License 2.0 条款兼容。可能还需要适当的归属。通常情况下，除非您绝对确定这样做是合适的，否则不要删除第三方或先前授权工作中现有的许可证头部。 +==== blog提交规范 -如果您不确定贡献的许可影响，请在提交前联系社区。 +（1）文件夹命名格式：**年-月-日-名称** -=== 适用于 PostgreSQL 上游的变更 + 示例：2022-1-28-ivorysql-arrived -如果您的变更涉及 PostgreSQL 和 IvorySQL 共享的功能，社区可能会要求您向前移植或向上游提议该变更。这有助于减少两个项目之间的长期分歧，并让广泛适用的变更在 PostgreSQL 生态系统中获得更广泛的评审。 +​ （2）文件属性统一为**index.md** -=== 补丁评审 +​ （3）图片属性统一为 **.png**形式，并将需要上传的图片提前放到要提交的文件夹中。 -提交的通过检查的 Pull Request 被视为可供同行评审。同行评审有助于确保变更符合项目质量标准、路线图方向和社区期望。 +​ **注意：**图片名字唯一，不可重复奥~。 -可能的评审结果包括请求额外提交、范围变更、测试改进或文档更新。请不要因迭代而气馁；这是开源协作的正常部分。 +​ 示例：po-one.png -当反馈延迟时，可以在 Pull Request 上留下礼貌的评论或通过社区渠道询问更新。 +==== blog编写规范 -=== 直接提交 +博客是用markdown或者Typora来编写，您可以阅读 https://docusaurus.io/zh-CN/docs/blog[博客 | Docusaurus]来了解博客的设计方式。 -有时，核心团队成员可能会直接提交小的非功能性修复。影响行为、测试或产品功能的变更应通过 Pull Request 工作流。 +（1）文章头部部署包括以下信息 + +```vim +--- +slug: IvorySQL +title: 欢迎来到IvorySQL社区 +authors: [official] +authorTwitter: IvorySql +tags: [IvorySQL, Welcome, Database, Join Us] +--- +``` + +​ **提示：**您可以将以上模板复制到您的文件夹中并进行编辑。 + +​ **注意：**1）slug、title、authors、tags后添加文字均空一格。 + +​ 2）slug每篇名字唯一且不可重复，相同文章中英文版可以相同。 + +（2）文本格式 + +​ 正文段落标题统一用**h2**/“**二级标题**”； + +​ 正文使用默认字体字号。 + +（3）插入照片命名形式 + +​ [Hello](Hello-banner.png) + +（4）插入超链接命名形式 + +​ [名称]（链接） + +​ [Github page](https://github.com/IvorySQL/) 下载源代码或发布的软件包。 + + +== 网站贡献指南 + +https://docs.ivorysql.org[IvorySQL的文档中心] 采用开源工具 https://antora.org/[`Antora`] 进行搭建，同样的，我们的文档中心也是开源的。文档中心由三部分组成，分别是 https://github.com/IvorySQL/ivorysql_docs[文档文件], https://github.com/IvorySQL/ivorysql_web[静态网页文件] 以及生成网页所用到的 https://github.com/IvorySQL/ivory-doc-builder[网页模板文件] 。 + +我们的文档中心同样欢迎每一位愿意参与到开源工作中的小伙伴的加入，记得遵守我们的行为准则^_^。 + +=== 如何贡献 + +由于我们的文档中心全部托管于Github上，这使得任何用户都可以将我们的文档仓库 `fork` 到个人仓库中，然后对其进行修改，之后提交PR，由我们的开源团队的人员审核过后就可以将修改更新到我们的文档中心中。 + +为了更加便捷地使您达到纠正文档错误的目的，首先需要您按照想要更新的大小来建立个人仓库，如下： + +* 如果您想修改原有的内容或者添加新的页面，仅需要 `fork` https://github.com/IvorySQL/ivorysql_docs[文档文件] 到个人仓库中。 + +image::7.png[] + +* 如果您想更深度地参与到文档中心的建设工作中来，除了文档文件外，还需要 `fork` https://github.com/IvorySQL/ivorysql_web[静态网页文件] 和 https://github.com/IvorySQL/ivory-doc-builder[网页模板文件] 到个人仓库中。 + +image::8.png[] +image::9.png[] + +=== 修改内容 + +本小节将会介绍发现网页内容不适宜之后，对网页内容进行修改的流程。 + +* 在有错误内容的网页的右上角，有一个 `edit this page` 的按钮，点击按钮。如图： + +image::10.png[] + +* 点击之后，就会跳转到我们存放当前页面源 `.adoc` 文件的编辑页面，请按照 `Asciidoc` 格式对内容进行修改。如图： + +image::11.png[] + +* 编辑完成后，如图： + +image::12.png[] + +* 确认更新后，如图： + +image::13.png[] + +* 接下来会由开源团队的相关人员负责审核您提交的内容，审核完成后您所提交的更新就会出现在对应页面上。 + +=== 添加页面 + +本小节会介绍如何在网站上添加新的页面组件，添加新页面涉及的修改主要包括以下几种： + +* `CN/modules/ROOT/pages/vX.X` 目录下的 `.adoc` 文件添加 +* `CN/modules/ROOT/nav.adoc` 的修改，如果修改涉及到图片的修改或者添加，请修改 `images` 中的图片 +* `EN/modules/ROOT/pages/vX.X` 目录下的 `.adoc` 文件添加 +* `EN/modules/ROOT/nav.adoc` 的修改，如果修改涉及到图片的修改或者添加，请修改 `images` 中的图片 + +1. 首先，您需要把您 `fork` 的仓库，clone到本地 + + git clone https://github.com/$username$/ivorysql_docs.git + +2. 然后，将要添加的 `.adoc` 文件放至正确目录下，切记中英文的都应该准备（*中英文文件应该同名*），并且各自放至正确目录下，同时，修改对应的 `nav.adoc` 文件（修改方式可以参照文件已有内容进行修改）。 +3. 上述修改完成后，先提交至个人仓库 + + git add . + git commit -m "$describe your change$" + git push + +4. 之后按照如下提交PR即可 + +image::13.png[] + +=== 测试 + +如果您不满足于简单的在网页端进行提交或者仅修改网页内容，又或者您想要修改网页ui，本小节内容将会帮助到您。 + +在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考<<#_如何贡献>>。 + +=== 部署网页 + +部署网页这部分工作，暂时还是由开源团队的人员负责，我们重视每一次提交和每一个issue，所以请不要担心自己对于社区的贡献被埋没^_^ + +=== Tip + +本章节主要介绍了如何自己主动去更新我们的文档中心，但是我们明确地知道山高路远，时不我待。因此对于没有太多时间的小伙伴来说，可以发邮件到我们的 **ivorysql-docs@ivorysql.org**，我们会有专门的工作人员进行处理您的每一封来信，期待您的邮件。 == 生态组件适配 @@ -469,6 +1420,3 @@ $PG_CONFIG --version 请先在 https://github.com/IvorySQL/IvorySQL/issues[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。 -== 致谢 - -感谢每一位参与 IvorySQL 的开发者、文档编辑者、测试人员和使用者。正是有了你们的付出，IvorySQL 才能不断成长！我们欢迎所有人参与 IvorySQL 社区贡献，我们的目标是发展一个由贡献者组成的活跃、健康的社区。 diff --git a/CN/modules/ROOT/pages/master/contribution/issue_submission_guide.adoc b/CN/modules/ROOT/pages/master/contribution/issue_submission_guide.adoc deleted file mode 100644 index 908c195..0000000 --- a/CN/modules/ROOT/pages/master/contribution/issue_submission_guide.adoc +++ /dev/null @@ -1,1012 +0,0 @@ - -:sectnums: -:sectnumlevels: 5 - -:imagesdir: ./_images -= **IvorySQL社区贡献指南** - -== **概述** - -=== 说明 - -IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvorySQL主存储库的提交权限。同时，我们非常渴望从更广泛的IvorySQL社区中的成员那里获得贡献。如果您希望看到您的代码或文档更改被添加到IvorySQL并出现在将来的版本中，本节的内容介绍是您需要知道的。 - -​IvorySQL社区欢迎并赞赏所有类型的贡献，期待您的加入！ - -=== 行为准则 - -作为成员，贡献者和领导者，我们每个人都应阅读我们的 *行为准则*。我们承诺让每个人都能参与社区，成为一种无骚扰的体验，无论年龄、体型、有形或无形的残疾、种族、性特征、性别认同和表达、经验水平、教育、社会经济地位、国籍、个人外表、种族、宗教或性身份和取向如何。 - -​ 我们承诺以有助于建立一个开放，热情，多样化，包容和健康社区的方式采取行动和互动。 - -=== 管理说明 - -团队是持续开放的团队，专注于IvorySQL项目的一部分。一个团队有其审查者、提交者和维护者，并拥有一个或多个存储库。团队级别的决策来自其维护者。IvorySQL开发人员的典型提升路径是从用户到审查者，然后是提交者和维护者。但获得更多的角色并不意味着你对其他社区成员拥有任何特权。IvorySQL社区中的每个人都是平等的，都有责任与其他贡献者进行建设性合作，建立一个友好的社区。这些角色是对您在IvorySQL开发中做出重大贡献的自然奖励，并为您在开发工作流中提供更多权利，以提高您的效率。同时，他们要求你承担一些额外的责任： - -​ 团队荣誉：现在您已经是团队评审员/提交者/维护者的成员，意味着您代表着项目和您的团队成员。所以，请做一个好人来捍卫球队的声誉。 - -​ 责任：提交者/维护者有权合并拉取请求，因此承担额外的责任来处理接受代码库或文档更改的后果。这包括在它导致问题时恢复或修复它，以及帮助发布经理解决发布前测试周期中发现的任何问题。 - -== **贡献者指南** - -在贡献之前，我们需要了解下IvorySQL目前的版本以及文档的版本。目前，我们维护着5.0等版本，我们的版本紧跟PG的更新步伐，贡献之前请更新至最新版本。之后我们需要细心浏览一下贡献的样式风格，熟悉代码贡献风格、提Issue样式、拉取PR标题样式、代码注释样式、文档贡献样式、文章贡献样式，这可以帮助您尽快成为IvorySQL的贡献者奥~。 - -=== 贡献前的准备 - -==== 开始 - -IvorySQL是在GitHub上开发的，任何希望对其作出贡献的人都必须拥有GitHub帐户，并熟悉Git工具和工作流。还建议您遵循开发人员的邮件列表，因为一些贡献可能会在那里产生更详细的讨论。 - -如果您有GitHub帐户，fork这个存储库至您的个人仓库中，这样您就可以拥有您的私人副本来开始hacking，并将其用作拉取请求的来源。 - -==== IvorySQL贡献的许可 - -如果您提交的贡献是原创作品，那么您可以假设IvorySQL将作为整个IvorySQL版本的一部分发布给下游用户，该版本将遵循**Apache许可证2.0版本**。 - -​ 如果您提交的内容不是原创作品，同样鼓励代码共享和尊重原作者的著作权，同样允许代码修改，再发布。***\*请注意需要满足如下条件\****： - -（1）需要给代码的用户一份Apache许可证。 - -（2）如果您修改了代码，需要在被修改的文件中说明。 - -（3）在延伸的代码中（修改和有源代码衍生的代码中）需要带有原来代码中的协议、商标、专利声明和其他原来作者规定需要包含的说明。 - -（4）如果再发布的产品中包含一个Notice文件，则在Notice文件中需要带有Apache许可证。您可以在Notice中增加自己的许可，但不可以表现为对Apache许可证构成更改。 - -​ 最后，请记住，从非原始的工作中删除许可标头从来都不是一个好主意。即使您使用的文件部分最初在顶部有许可标头，您也应该保留它。与往常一样，如果您不太确定您的贡献所涉及的许可问题，请随时在开发人员邮件列表中联系我们。 - - -=== 您可以做什么贡献 - -==== 贡献代码 - -可以将自己修改的bug、新增的功能等代码上传至个人仓库，最后提交PR请求合并至官网：https://github.com/IvorySQL/IvorySQL 。 - -==== 文档贡献 - -IvorySQL社区提供的是中英文文档。英文文档保存在...文档存储库中，中文文档保存在i18n文档存储库中。您可以为任一文档存储库做出贡献。 - -==== 测试IvorySQL和报告问题 - -GitHub: https://github.com/IvorySQL/IvorySQL - -​码云：https://gitee.com/IvorySQL/ - - -==== 参与IvorySQL网站建设 - -IvorySQL官网下载：https://github.com/IvorySQL/Ivory-www - - -==== 回答邮件列表问题 - -邮件列表位于 官网下：https://lists.ivorysql.org/ - -==== 贡献文章 - -您可以在IvorySQL-WWW代码仓库自己提交至blog贡献，也可以联系我们IvorySQL小助理发送至邮箱ivorysql@highgo.com 。 - -=== 如何做出贡献 - -==== 编码指南 - -您获得反馈和看到代码合并到项目中的机会在很大程度上取决于更改的粒度。如果您的想法发生了更大的变化，我们强烈建议您在花大量时间编写代码之前，先加入开发人员的邮件列表，并与我们分享您的建议。即使您的建议得到社区的验证，我们仍然建议您将实际工作作为一系列小型的、独立的提交来完成。这使得评审员的工作更加容易，并提高了反馈的及时性。 - -​ 当谈到IvorySQL的C和C++部分时，我们尝试遵循PostgreSQL编码约定。除此之外： - -​ 对于C和Perl代码，如果需要，请运行pgindent。我们建议在查看更改时使用git diff--color，这样您提交的代码中就不会出现任何虚假的空白问题。 - -​ 所有贡献给IvorySQL的新功能都应该有与其一起贡献的回归测试覆盖。如果您不确定如何测试或记录您的工作，请在ivorysql-hackers邮件列表中提出问题，社区的开发人员将尽力帮助您。 - -​ 至少，您应该始终运行make install check world，以确保您没有破坏任何东西。 - -==== 适用于上游PostgreSQL的更改 - -如果您正在进行的更改涉及PostgreSQL和IvorySQL之间的通用功能，则可能会要求您将其转发到PostgreSQL。这不仅是为了我们不断减少两个项目之间的差异，而且是为了让与PostgreSQL相关的任何变化都能从对上游PostgreSQL社区更广泛的审查中受益。一般来说，将这两个代码库都放在手边是个好主意，这样您就可以确定您的更改是否需要前移。 - -==== 补丁提交 - -一旦您准备好与IvorySQL核心团队和IvorySQL社区的其他成员共享您的工作，您应该将所有提交推送到从官方IvorySQL派生的您自己的存储库中，并向我们发送请求。 - -==== 补丁审查 - -假定提交的拉取请求通过验证检查，可供同行审查。同行审查是确保对IvorySQL的贡献具有高质量并与路线图和社区期望保持一致的过程。我们鼓励IvorySQL社区的每个成员审查请求并提供反馈。由于您不必成为核心团队成员就可以做到这一点，因此我们建议您向有兴趣成为IvorySQL长期贡献者的任何人提供一系列拉动式评论。 - -​ 同行评审的一个结果可能是达成共识，即您需要以某些方式修改pull请求。GitHub允许您将其他提交推送到从中发送请求的分支中。这些额外的提交将对所有审阅者可见。 - -​ 当同行评议收到参与者至少+1张+1和no-1张的选票时，同行评议会趋于一致。在这一点上，您应该期望核心团队成员之一将您的更改引入到项目中。 - -在补丁审查期间的任何时候，您都可能会因审查人员和核心团队成员的工作效率而遇到延迟。请耐心点，也不要气馁。如果您在几天内没有收到预期的反馈，请添加一条评论，要求更新pull请求本身，或者向邮件列表发送一封电子邮件。 - -==== 直接提交到存储库 - -有时，您会看到核心团队成员直接提交到存储库，而无需执行pull请求工作流。这仅适用于小的更改，我们使用的经验法则是：如果更改涉及任何可能导致测试失败的功能，那么它必须通过pull请求工作流。另一方面，如果更改发生在代码库的非功能部分（例如在注释块中修复打字错误），则核心团队成员可以决定直接提交到存储库。 - -== **提Issue** - -=== 第1步 进入New issue 页面： - -1、进入 IvorySql官网：https://github.com/IvorySQL/IvorySQL - -​2、点击New issue - -image::p3.png[] - - -=== 第2步：选择需要填写的issue类型 - -**1、bug report** - -``` -Title: 标题 -``` - -``` -## Bug Report -对bug进行描述 - - -\### IvorySQL Version -在IvorySQL哪个版本发现的问题 - -\### OS Version (uname -a) -系统版本 - -\### Configuration options ( config.status --config ) -配置参数 - -\### Current Behavior -当前的结果 - -\### Expected behavior/code -期望的结果 - -\### Step to reproduce -复现步骤 - -\### Additional context that can be helpful for identifying the problem -有助于识别问题的其它信息 -``` - - -**2、Enhancement** - -``` -Title: 标题 -``` - -``` -## Enhancement -对于期望强化的功能作一个描述 -``` - -**3、Feature Request** - -``` -Title: 标题 -``` - -``` -## Feature Request -描述你期望实现的一个功能 -``` - - -=== 第3步：提交 - -点击 submit new issue 按钮, 提交即可 - -== **贡献代码** - -=== 第1步: Fork https://ivorysql.org/[ivorysql.org]仓库 - -1、打开ivorysql仓库 https://github.com/IvorySQL/IvorySQL - -2、点击右上角fork按钮，等待fork完成 - -=== 第2步:将fork的仓库克隆至本地 - -``` -cd $working_dir # 将 $working_dir 替换为你想放置 repo 的目录。例如，`cd ~/Documents/GitHub` - -git clone git@github.com:$user/IvorySQL.git # 将 `$user` 替换为你的 GitHub ID -``` - -=== 第3步：创建一个新的Branch - -``` -cd $working_dir/IvorySQL - -git checkout -b new-branch-name -``` - -=== 第4步：编辑文档或修改代码 - -在新建的new-branch-name中修改代码。 - -=== 第5步：生成commit - -``` -Git add - -Git commit -m “commit-message” -``` - -=== 第6步：将修改推送至远端 - -``` -Git push -u origin new-branch-name -``` - -=== 第7步：创建一个Pull Request - -1、打开你 Fork 的仓库： https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL]（将 $user 替换为你的 GitHub ID）。 - -2、点击 Compare & pull request 按钮即可创建 PR。 - -== **提交PR** - -对于提交一个PR应该保持一个功能，或者一个bug提交一次。禁止多个功能一次提交。 - - -=== 第1步：创建一个Pull Request - -1、打开你 Fork 的仓库： https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL]（将 $user 替换为你的 GitHub ID）。 - -​ 2、点击 Compare & pull request 按钮 - -=== 第2步：填写PR信息 - -``` -Fix test -功能描述 -``` - -``` -leave a comment -对该提交功能进行比较详细的描述 -``` - -=== 第3步：提交PR - -点击Create pull request 按钮即可提交。 - -== **编写文档** - -=== 准备工作 - -（1）下载Markdown或者Typora文档编辑器。 - -（2）检查源仓库是否有更新，如果有更新请先更新并同步到自己的仓库。如有更新请参阅以下步骤，更新至最新版本： - -``` -git remote - -git fetch upstream - -git merge upstream/main - -git push -``` - -（3）熟悉样式风格（规范说明） - -=== 贡献地方 - -IvorySQL社区提供双语文档。英文文档保存在IvorySQL/文档存储库（文档存储库）中，中文文档保存在 IvorySQL/文档-i18n存储库（文档-i18n 存储库）中。您可以为任何一方文档做出贡献，当然您也可以为两方同时做出贡献。 - -​ 您可以从以下任何一项开始，以帮助改进IvorySQL网站（英文和 -i18n）上的 IvorySQL文档： - -​ (1) 编写完善文档 - -​ (2) 修复拼写错误或格式（标点符号、空格、缩进、代码块等） - -​ (3) 修正或更新不当或过时的说明 - -​ (4) 添加缺少的内容（句子、段落或新文档） - -​ (5) 将文档更改从英文翻译成中文，或从中文翻译成英文。 - -​ (6) 提交、回复和解决文档问题或文档-i18n问题 - -​ (7) （高级）查看其他人创建的拉取请求 - -=== 规范说明 - -IvorySQL文档是用“markdown”编写的。为确保格式的质量和一致性，在修改更新文档时应遵循某些 Markdown 规则。 - -​ **Markdown规范** - -​ 1、标题从一级开始递增使用，禁止跳级使用。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。 - -​ 2、标题必须统一使用 ATX 风格，即在标题前加 # 号来表示标题级别。 - -​ 3、标题的引导符号 # 后必须空一格再接标题内容。 - -​ 4、标题的引导符号“#”后只能空一格后再接标题内容，不能有多个空格。 - -​ 5、标题必须出现在一行行首，即标题的 # 号前不能有任何空格。 - -​ 6、标题末尾仅能出现中英文问号、反引号、中英文单双引号等符号。其余如冒号、逗号、句号、感叹号等符号均不能在标题末尾使用。 - -​ 7、标题上面须空一行。 - -​ 8、文档中不能连续出现内容重复的标题，如一级标题为 # IvorySQL 架构，紧接着的二级标题就不能是 ## IvorySQL 架构。如果不是连续的标题，则标题内容可重复。 - -​ 9、文档中只能出现一个一级标题。 - -​ 10、一般来说，除 TOC.md 文件可缩进 2 个空格外，其余所有 .md 文件每缩进一级，默认须缩进 4 个空格。 - -​ 11、文档中（包括代码块内）禁止出现 Tab 制表符，如需缩进，必须统一用空格代替 - -​ 12、禁止出现连续的空行。 - -​ 13、块引用符号 > 后禁止出现多个空格，只能使用一个空格，后接引用内容。 - -​ 14、使用有序列表时，必须从 1 开始，按顺序递增。 - -​ 15、使用列表时，每一列表项的标识符（+、-、* 或数字）后只能空一格，后接列表内容。 - -​ 16、列表（包括有序和无序列表）前后必须各空一行。 - -​ 17、代码块前后必须各空一行。 - -​ 18、文档中禁止出现裸露的 URL。如果希望用户能直接点击并打开该 URL，则使用一对尖括号 () 包裹该 URL。如果由于特殊情况必须使用裸露的 URL，不需要用户通过点击打开，则使用一对反引号 (`URL`) 包裹该 URL。 - -​ 19、使用加粗、斜体等强调效果时，在强调标识符内禁止出现多余的空格。如不能出现 `** 加粗文本 **`。 - -​ 20、单个反引号包裹的代码块内禁止出现多余的空格。如不能出现 ` 示例文本 `。 - -​ 21、链接文本两边禁止出现多余的空格。如不能出现 [某链接](https://www.example.com/)。 - -​ 22、链接必须有链接路径。如不能出现[空链接]()或[空链接](#)等情况。 - -=== 示例 - -1、标题从一级开始递增使用，禁止跳级使用。 - -``` -# Heading 1 -### Heading 3 - -We skipped out a 2nd level heading in this document -``` - - - -2、标题必须统一使用 ATX 风格，即在标题前加 # 号来表示标题级别。 - -``` -# Heading 1 -## Heading 2 -### Heading 3 -#### Heading 4 -## Another Heading 2 -### Another Heading 3 -``` - - - -3、标题的引导符号 # 后必须空一格再接标题内容。禁止#后多个空格，禁止#前出现空格 - -错误示范： - -``` -# Heading 1 -## Heading 2 -``` - -正确示范： - -``` -# Heading 1 -## Heading 2 -``` - - - -4、标题末尾仅能出现中英文问号、反引号、中英文单双引号等符号。 - -错误示范 - -``` -# This is a heading. -``` - -正确示范 - -``` -# This is a heading -``` - - - -5、标题上面空一行 - -错误示范 - -``` -# Heading 1 -Some text -Some more text## Heading 2 -``` - -正确示范 - -``` -# Heading 1 -Some text -Some more text - -## Heading 2 -``` - - - -6、文档中不能连续出现内容重复的标题，如一级标题为 # IvorySQL 描述，紧接着的二级标题就不能是 ## IvorySQL 描述。如果不是连续的标题，则标题内容可重复。 - -错误示范 - -``` -# Some text - -## Some text -``` - -正确示范 - -``` -# Some text - -## Some more text -``` - - - -7、文档中只能出现一个一级标题。 - -错误示范 - -``` -# Top level heading - -# Another top-level heading -``` - -正确示范 - -``` -# Title - -## Heading - -## Another heading -``` - - - -8、一般来说，除 TOC.md 文件可缩进 2 个空格外，其余所有 .md 文件每缩进一级，默认须缩进 4 个空格。 - -错误示范 - -``` -* List item - * Nested list item indented by 3 spaces -``` - -正确示范: - -``` -* List item - * Nested list item indented by 4 spaces -``` - - - -9、文档中（包括代码块内）禁止出现 Tab 制表符，如需缩进，必须统一用空格代替 - -错误示范： - -``` -Some text - * hard tab character used to indent the list item -``` - -正确示范: - -``` -Some text - * Spaces used to indent the list item instead -``` - - - -10、禁止出现连续的空行 - -错误示范 - -``` -Some text here - - -Some more text here -``` - -正确示范: - -``` -Some text here - -Some more text here -``` - - - -11、块引用符号 > 后禁止出现多个空格，只能使用一个空格，后接引用内容。 - -错误示范 - -``` -> This is a blockquote with bad indentation> there should only be one. -``` - -正确示范 - -``` -> This is a blockquote with correct> indentation. -``` - - - -12、使用有序列表时，必须从 1 开始，按顺序递增。 - -错误示范: - -``` -1. Do this. -1. Do that. -1. Done. -``` - -``` -0. Do this. -1. Do that. -2. Done. -``` - - 正确示范: - -``` -1. Do this. -2. Do that. -3. Done. -``` - - - -13、使用列表时，每一列表项的标识符（+、-、* 或数字）后只能空一格，后接列表内容。 - -正确示范 - -``` -* Foo -* Bar -* Baz - -1. Foo - * Bar -1. Baz -``` - - - -14、列表（包括有序和无序列表）前后必须各空一行。 - -错误示范 - -``` -Some text* Some* List - -1. Some2. List - -Some text -``` - -正确示范 - -``` -Some text - -* Some -* List - -1. Some -2. List - -Some text -``` - - - -15、代码块前后必须各空一行。 - -错误示范 - -``` -Some text -​``` -Code block -​``` -​``` -Another code block -​``` -Some more text -``` - -正确示范 - -``` -Some text - -​``` -Code block -​``` - -​``` -Another code block -​``` - -Some more text -``` - - - -16、文档中禁止出现裸露的 URL。如果希望用户能直接点击并打开该 URL，则使用一对尖括号 () 包裹该 URL。如果由于特殊情况必须使用裸露的 URL，不需要用户通过点击打开，则使用一对反引号 (`URL`) 包裹该 URL。 - -错误示范 - -``` -For more information, see https://www.example.com/. -``` - -正确示范 - -``` -For more information, see . -``` - - - -17、使用加粗、斜体等强调效果时，在强调标识符内禁止出现多余的空格。如不能出现 `** 加粗文本 **`。 - -错误示范 - -``` -Here is some ** bold ** text. - -Here is some * italic * text. - -Here is some more __ bold __ text. - -Here is some more _ italic _ text. -``` - -正确示范: - -``` -Here is some **bold** text. - -Here is some *italic* text. - -Here is some more __bold__ text. - -Here is some more _italic_ text. -``` - - - -18、单个反引号包裹的代码块内禁止出现多余的空格。如不能出现 ` 示例文本 `。 - -错误示范： - -``` -some text - some text -``` - -正确示范: - -``` -some text -``` - - - -19、链接文本两边禁止出现多余的空格。如不能出现 [ 某链接 ](https://www.example.com/)。 - -错误示范 - -``` -[ a link ](https://www.example.com/) -``` - -正确示范: - -``` -[a link](https://www.example.com/) -``` - - - -20、链接必须有链接路径。如不能出现[空链接]()或[空链接](#)等情况。 - -错误示范 - -``` -[an empty link]() - -[an empty fragment](#) -``` - -正确示范: - -``` -[a valid link](https://example.com/) - -[a valid fragment](#fragment) -``` - - - -21文档中的代码块统一使用三个反引号进行包裹，禁止使用缩进四格风格的代码块。 - -错误示范： - -``` -Some text. - - # Indented code - -More text. -``` - -正确示范 - -``` -```ruby -# Fenced code -​``` -More text. -``` - -=== 环境准备 - -为了测试您所做的修改是否修改，您需要准备以下环境 - -* `Node.js` 安装 -* `Antora` 安装 - -环境安装请参考 https://docs.antora.org/antora/latest/[Antora docs]。 - -安装成功后，在终端上显示如下即为成功安装。 - -image::14.png[] - - -=== 网页生成 - -通过阅读之前内容，相信您已经有了充足的准备，包括 `fork` 我们文档中心相关的三个仓库到个人仓库中，`Antora` 工具的安装准备等环境的搭建。 - -* 首先，您要知道网页对应的ui的位置，如下图： - -image::15.png[] - -中英文的网页ui模板基本一致，因此修改时应该尽量保证同时修改两个模板，将修改过后的ui再上传至个人Github上，完成了这些，就可以考虑在本地生成您修改过后的网页了。 - -文档中心是由 `Antora` 进行搭建的，在运行 `Antora` 之前，记得修改对应 `playbook.yml` 文件 - -image::16.png[] -image::17.png[] - -完成上述流程之后，请在终端运行命令 `antora antora-playbook.yml --stacktrace`，然后耐心等待，当成功运行结束后，你就可以查看自己生成的网页了。 - -在检查之后，你就可以开始着手上传至我们的 *ivorysql_web* 仓库中，提交PR的流程和之前的流程相同，感谢您对社区的贡献^_^，我们会在审核过后，考虑是否更新网站。 - -== 提交blog - -=== 准备工作 - -1、下载 https://markdown.com.cn/tools.html#%E7%BC%96%E8%BE%91%E5%99%A8[Markdown]或者 https://typoraio.cn/[Typora]文档编辑器。 - -​ 2、先下载博客源码到本地，检查源仓库(https://github.com/IvorySQL/Ivory-www)是否有更新， 如果有更新请先更新并同步到自己的仓库。请参阅以下步骤，更新至最新版本： - -``` bash -# 拉取网站源码 -git clone https://github.com/IvorySQL/Ivory-www.git -# 同步更新仓库 -git pull -``` - -​ 3、熟悉样式风格 (<<#_规范说明_2>>) - -=== 贡献地方 - -IvorySQL社区提供双语文档。英文博客保存在源码目录**Ivory-www/blog**中，中文博客保存在源码目录**Ivory-www/i18n/zh-CN/docusaurus-plugin-content-blog**中。您可以为任何一方博客做出贡献，当然您也可以为两方同时做出贡献。 - -=== 如何贡献 - -在贡献之前，让我们快速浏览一下有关IvorySQL博客维护的信息。这可以帮助您尽快成功的提交blog成为贡献者。blog提交规范 - -​ （1）将代码克隆到本地仓库 - -``` bash -git clone https://github.com/IvorySQL/Ivory-www.git -``` - -​ （2）创建一个分支 - -```bash -git checkout -b -``` - -​ （3）在博客目录中创建自己文章的目录，目录名字规则参照 (<<#_规范说明_2>>)。 - -```bash -# 生成英文博客目录及文件 -cd Ivory-www/blog -mkdir -cd -touch index.md -# 生成中文博客目录及文件 -cd Ivory-www/i18n/zh-CN/docusaurus-plugin-content-blog -mkdir -cd -touch index.md -``` - -​ （4）在index.md编写要发布的博文，将博客中需要的图片放到和index.md同级目录。 - -​ （5）提交发布博客 - -```bash -git add -git commit -m "" -git push origin : -``` - -=== 规范说明 - -==== blog提交规范 - -（1）文件夹命名格式：**年-月-日-名称** - - 示例：2022-1-28-ivorysql-arrived - -​ （2）文件属性统一为**index.md** - -​ （3）图片属性统一为 **.png**形式，并将需要上传的图片提前放到要提交的文件夹中。 - -​ **注意：**图片名字唯一，不可重复奥~。 - -​ 示例：po-one.png - -==== blog编写规范 - -博客是用markdown或者Typora来编写，您可以阅读 https://docusaurus.io/zh-CN/docs/blog[博客 | Docusaurus]来了解博客的设计方式。 - -（1）文章头部部署包括以下信息 - -```vim ---- -slug: IvorySQL -title: 欢迎来到IvorySQL社区 -authors: [official] -authorTwitter: IvorySql -tags: [IvorySQL, Welcome, Database, Join Us] ---- -``` - -​ **提示：**您可以将以上模板复制到您的文件夹中并进行编辑。 - -​ **注意：**1）slug、title、authors、tags后添加文字均空一格。 - -​ 2）slug每篇名字唯一且不可重复，相同文章中英文版可以相同。 - -（2）文本格式 - -​ 正文段落标题统一用**h2**/“**二级标题**”； - -​ 正文使用默认字体字号。 - -（3）插入照片命名形式 - -​ [Hello](Hello-banner.png) - -（4）插入超链接命名形式 - -​ [名称]（链接） - -​ [Github page](https://github.com/IvorySQL/) 下载源代码或发布的软件包。 - - -== 网站贡献指南 - -https://docs.ivorysql.org[IvorySQL的文档中心] 采用开源工具 https://antora.org/[`Antora`] 进行搭建，同样的，我们的文档中心也是开源的。文档中心由三部分组成，分别是 https://github.com/IvorySQL/ivorysql_docs[文档文件], https://github.com/IvorySQL/ivorysql_web[静态网页文件] 以及生成网页所用到的 https://github.com/IvorySQL/ivory-doc-builder[网页模板文件] 。 - -我们的文档中心同样欢迎每一位愿意参与到开源工作中的小伙伴的加入，记得遵守我们的行为准则^_^。 - -=== 如何贡献 - -由于我们的文档中心全部托管于Github上，这使得任何用户都可以将我们的文档仓库 `fork` 到个人仓库中，然后对其进行修改，之后提交PR，由我们的开源团队的人员审核过后就可以将修改更新到我们的文档中心中。 - -为了更加便捷地使您达到纠正文档错误的目的，首先需要您按照想要更新的大小来建立个人仓库，如下： - -* 如果您想修改原有的内容或者添加新的页面，仅需要 `fork` https://github.com/IvorySQL/ivorysql_docs[文档文件] 到个人仓库中。 - -image::7.png[] - -* 如果您想更深度地参与到文档中心的建设工作中来，除了文档文件外，还需要 `fork` https://github.com/IvorySQL/ivorysql_web[静态网页文件] 和 https://github.com/IvorySQL/ivory-doc-builder[网页模板文件] 到个人仓库中。 - -image::8.png[] -image::9.png[] - -=== 修改内容 - -本小节将会介绍发现网页内容不适宜之后，对网页内容进行修改的流程。 - -* 在有错误内容的网页的右上角，有一个 `edit this page` 的按钮，点击按钮。如图： - -image::10.png[] - -* 点击之后，就会跳转到我们存放当前页面源 `.adoc` 文件的编辑页面，请按照 `Asciidoc` 格式对内容进行修改。如图： - -image::11.png[] - -* 编辑完成后，如图： - -image::12.png[] - -* 确认更新后，如图： - -image::13.png[] - -* 接下来会由开源团队的相关人员负责审核您提交的内容，审核完成后您所提交的更新就会出现在对应页面上。 - -=== 添加页面 - -本小节会介绍如何在网站上添加新的页面组件，添加新页面涉及的修改主要包括以下几种： - -* `CN/modules/ROOT/pages/vX.X` 目录下的 `.adoc` 文件添加 -* `CN/modules/ROOT/nav.adoc` 的修改，如果修改涉及到图片的修改或者添加，请修改 `images` 中的图片 -* `EN/modules/ROOT/pages/vX.X` 目录下的 `.adoc` 文件添加 -* `EN/modules/ROOT/nav.adoc` 的修改，如果修改涉及到图片的修改或者添加，请修改 `images` 中的图片 - -1. 首先，您需要把您 `fork` 的仓库，clone到本地 - - git clone https://github.com/$username$/ivorysql_docs.git - -2. 然后，将要添加的 `.adoc` 文件放至正确目录下，切记中英文的都应该准备（*中英文文件应该同名*），并且各自放至正确目录下，同时，修改对应的 `nav.adoc` 文件（修改方式可以参照文件已有内容进行修改）。 -3. 上述修改完成后，先提交至个人仓库 - - git add . - git commit -m "$describe your change$" - git push - -4. 之后按照如下提交PR即可 - -image::13.png[] - -=== 测试 - -如果您不满足于简单的在网页端进行提交或者仅修改网页内容，又或者您想要修改网页ui，本小节内容将会帮助到您。 - -在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考<<#_如何贡献>>。 - -=== 部署网页 - -部署网页这部分工作，暂时还是由开源团队的人员负责，我们重视每一次提交和每一个issue，所以请不要担心自己对于社区的贡献被埋没^_^ - -=== Tip - -本章节主要介绍了如何自己主动去更新我们的文档中心，但是我们明确地知道山高路远，时不我待。因此对于没有太多时间的小伙伴来说，可以发邮件到我们的 **ivorysql-docs@ivorysql.org**，我们会有专门的工作人员进行处理您的每一封来信，期待您的邮件。 - diff --git a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc deleted file mode 100644 index ef2dfea..0000000 --- a/EN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ /dev/null @@ -1,472 +0,0 @@ -:sectnums: -:sectnumlevels: 5 - -:imagesdir: ./_images - -= IvorySQL Contribution Guide - -IvorySQL grows through contributions from developers, testers, documentation writers, translators, community advocates, and users around the world. This guide will help you understand how to participate in the IvorySQL community, from getting started to making in-depth contributions. - -== Roles and Responsibilities - -Before contributing, please confirm your current participation role to more efficiently understand the contribution methods suitable for you: - -=== Users - -As a user, you play an important role in using IvorySQL. We encourage you to: - -==== Provide Feedback and Requirements - -* Found a bug, performance issue, or inaccurate documentation? -* Have new feature suggestions or usage experience improvements? - -If you are preparing to report a bug or submit requirements to the community, please submit an Issue in the corresponding IvorySQL community repository and refer to the Issue xref:master/contribution/issue_submission_guide.adoc[Submission Guide]. - -==== Participate in Community Discussions - -* Discuss through the https://lists.ivorysql.org[mailing list] -* Join https://github.com/IvorySQL/IvorySQL/discussions[GitHub Discussions] to supplement information or verify issues -* Participate in technical discussions in WeChat, Discord, and other chat groups - -=== Contributors - -We welcome all types of contributions including code, documentation, and testing. - -==== Find Projects You're Interested In - -We divide the repository into multiple sub-projects. You can find projects of interest and their code repositories from the following list: - -[cols="1,1"] -|=== -|Repository | Description - -|https://github.com/IvorySQL/IvorySQL[IvorySQL] | Responsible for the development and maintenance of the IvorySQL database -|https://github.com/IvorySQL/Ivory-www[Ivory-www] | Responsible for the development and maintenance of the community website -|https://github.com/IvorySQL/ivory-operator[ivory-operator] | Responsible for the development and maintenance of IvorySQL cloud-native database and peripheral tools -|https://github.com/IvorySQL/docker_library[docker_library] | Responsible for the construction and maintenance of IvorySQL multi-architecture images -|https://github.com/IvorySQL/ivory-cloud[ivory-cloud] | Responsible for the development and maintenance of IvorySQL cloud service platform and peripheral ecosystem -|https://github.com/IvorySQL/ivorysql_docs[Ivorysql_docs] | Responsible for the development and maintenance of the community documentation center -|https://github.com/IvorySQL/ivory-doc-builder[ivory-doc-builder] | Responsible for compiling Ivorysql_docs -|https://github.com/IvorySQL/ivorysql_web[Ivorysql_web] | Responsible for the maintenance of the community documentation website -|https://github.com/IvorySQL/ivorysql-wasm[Ivorysql_wasm] | Responsible for the development and maintenance of the IvorySQL online experience website -|=== - -==== Assign Issues to Yourself - -You can assign Issues you created or Issues you are willing to handle to yourself. Simply enter `/assign` in the comment box, and the bot will assign the issue to you. There may already be communication and discussion among participants under each Issue. If you are interested, you can also express your opinions in the comment box to participate in Issue discussions. - -=== Maintainers - -Maintainers are responsible for managing IvorySQL code, PR reviews, leading version releases, and IvorySQL development direction. - -==== Community Planning - -* Develop version planning and Roadmap -* Track and evaluate community needs -* Maintain a public TODO list - -==== Code Management - -* Participate in Pull Request reviews -* Review security issues to ensure project health - -==== Process and Governance Mechanisms - -* Optimize collaboration mechanisms (code contribution guides, PR templates, etc.) -* Establish vulnerability response mechanisms and codes of conduct - -== Getting Started - -=== Register a GitHub Account - -Whether you want to submit Issues, participate in discussions, or contribute code and documentation, you need to log in with a GitHub account and interact with the IvorySQL project. - -Please refer to to register your GitHub account and familiarize yourself with Git tools and workflows. - -IvorySQL source code is hosted on GitHub: . - -=== Sign the CLA - -Before submitting code or documentation contributions, individual or corporate contributors need to sign the Contributor License Agreement (CLA) to ensure code legality and compliance. Signing the CLA is a necessary condition for the IvorySQL community to accept contributions, ensuring your contributions are legally distributed. Please download the CLA according to the following links, sign it, and send the signed CLA to cla@ivorysql.org. - -* https://www.ivorysql.org/zh-CN/assets/files/individual_cla-a81f001209eb5ce0f8ea7c3be4cc69b5.pdf[Individual Contributor] -* https://www.ivorysql.org/zh-CN/assets/files/corporate_cla-76e89b6f17b0bc102cbc1105d438a917.pdf[Corporate Contributor] - -Pull requests from contributors who have not signed the CLA cannot proceed to formal review. - -== Code Contributions - -=== Environment Preparation - -IvorySQL development and collaboration happen on GitHub. Before contributing, it is recommended that you: - -* Have a GitHub account and be familiar with basic Git workflows -* Fork the official repository and work on a dedicated branch in your own fork -* Follow community discussions or mailing lists when relevant, especially for larger proposals - -=== Patch Submission - -We recommend the following contribution flow: - -. Choose an entry point from GitHub issues, documentation gaps, community activities, or ecosystem needs. -. For larger changes, discuss the proposal first in an issue, pull request thread, or mailing list to reduce rework. -. Fork the repository and create a focused branch for one self-contained change. -. Complete the implementation, tests, or documentation updates and review your own changes locally. -. Submit a pull request to the official repository, or use issues and discussions for non-code contributions. -. Respond to review feedback, push follow-up commits when needed, and iterate until the change is ready to merge. - -=== Coding and Testing Guidelines - -To improve review quality and merge efficiency, we recommend the following: - -* Split larger ideas into a series of small, self-contained commits whenever possible. -* Follow PostgreSQL coding conventions for C and C++ related changes. -* Run `pgindent` for C and Perl code when needed. -* Use `git diff --color` before submission to catch accidental whitespace-only changes. -* Add regression tests for new functionality whenever possible. -* At minimum, run `make installcheck-world` to ensure your changes do not introduce obvious regressions. - -If you are unsure how to test or document a change, ask on the `ivorysql-hackers` mailing list and the community will do its best to help. - -=== Licensing of Contributions - -If the contribution you are submitting is original work, you can assume it will be released as part of IvorySQL under the Apache License, Version 2.0. - -If the contribution is not original work, you must clearly indicate the original license and ensure it is compatible with Apache License 2.0 terms. Proper attribution may also be required. In general, never remove an existing license header from third-party or previously licensed work unless you are absolutely certain it is appropriate to do so. - -If you are unsure about the licensing implications of your contribution, please contact the community before submitting it. - -=== Changes Applicable to PostgreSQL Upstream - -If your change touches functionality shared by PostgreSQL and IvorySQL, the community may ask you to forward-port or propose the change upstream. This helps reduce long-term divergence between the two projects and gives broadly useful changes access to wider review in the PostgreSQL ecosystem. - -=== Patch Review - -A submitted pull request with passing checks is considered available for peer review. Review feedback helps ensure that changes are aligned with project quality standards, roadmap direction, and community expectations. - -Possible review outcomes include requests for additional commits, changes in scope, testing improvements, or documentation updates. Please do not be discouraged by iteration; it is a normal part of open-source collaboration. - -When feedback is delayed, it is fine to leave a polite comment on the pull request or ask for an update through the community channels. - -=== Direct Commits - -Small non-functional fixes may occasionally be committed directly by core team members. Changes that affect behavior, testing, or product functionality should go through the pull request workflow. - -== Ecosystem Component Adaptation - -As an Oracle-compatible database built on PostgreSQL, IvorySQL naturally inherits PostgreSQL's rich extension ecosystem. To enable more PostgreSQL ecosystem components to run stably on IvorySQL, the IvorySQL community welcomes external contributors to participate in ecosystem component adaptation work. - -=== Adaptation Scope - -The following types of components are welcome for adaptation contributions: - -* Official PostgreSQL community extensions (contrib modules) -* Third-party plugins developed based on PostgreSQL's extension mechanism -* Peripheral ecosystem tools that work alongside the database as independent processes, such as connection pools, proxies, and middleware - -=== Contribution Process - -Ecosystem component adaptation is the work of adapting PostgreSQL ecosystem components to run on IvorySQL. The main activities include: understanding the target component's characteristics, principles, and usage; testing whether it works correctly under IvorySQL's PG mode and Oracle compatibility mode; and finally, based on the above research and testing, writing an ecosystem component adaptation document and submitting it to the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository. After the document is submitted, maintainers will reproduce the test of the target component following the steps given in the adaptation document; once they confirm the test results are consistent with the document, they will merge the PR. - -For the specific steps of topic selection, testing, and documentation writing, please refer to the detailed steps below. - -==== Step 1: Topic Selection and Communication - -===== Confirm the Component Is Not Yet Adapted - -Before starting adaptation work, please check the xref:master/ecosystem_components/ecosystem_overview.adoc[Ecosystem Component Adaptation List] to confirm whether the target component has already been adapted. If the target component is not in the list, continue with the following process; otherwise, please choose another unadapted component. - -===== Claim or Create an Issue - -Search for the target component in the https://github.com/IvorySQL/IvorySQL/issues[Issue list] of the IvorySQL repository: - -- If a related adaptation Issue already exists, first confirm it has not yet been assigned (the Assignees field is empty), then click `Assign yourself` in the Assignees area in the upper-right corner to claim the Issue; if it has already been claimed by someone else, please choose another component. -- If no related Issue exists yet, create a new `Feature Request` Issue, add the `compatibility` label, and assign it to yourself. You can refer to existing ecosystem component adaptation Issues for the format: the title should follow the pattern `Ecosystem Integration: `, and the body should describe the component to be adapted and its use in one sentence. - -Maintainers will evaluate whether the component is suitable for inclusion in the IvorySQL ecosystem and communicate with you through the Issue. - -[TIP] -It is recommended to start adaptation work only after receiving confirmation from maintainers to avoid duplicate or unnecessary work. - -===== Sign the CLA - -Before submitting documentation contributions, please ensure you have signed the Contributor License Agreement (CLA). For details, please refer to the xref:#_sign_the_cla[Sign the CLA] section of this guide. - -==== Step 2: Environment Preparation - -===== IvorySQL Environment - -Please prepare an IvorySQL environment for testing, preferably meeting the following requirements: - -* IvorySQL version: 5.0 or above -* Operating system: Ubuntu 24.04 (x86_64) or other mainstream Linux distributions recommended -* Installation path: Note the IvorySQL installation path, as the `pg_config` path will be needed when compiling extensions later - -[TIP] -You can quickly set up a test environment using IvorySQL's official Docker images. Refer to xref:master/containerization/docker_podman_deployment.adoc[Docker & Podman Deployment]. - -===== Build Toolchain - -Prepare the appropriate toolchain based on the target component's build method: - -* C/C++ extensions: gcc, make, and other basic build tools -* Rust extensions: cargo, rustc, and other Rust toolchain components -* Extensions in other languages: corresponding language runtime environments - -==== Step 3: Adaptation Testing - -The goals of ecosystem component adaptation are divided into two levels: - -- PG mode: the component must be fully usable. -- Oracle compatibility mode: it should be fully usable if possible; if it cannot be fully usable, at least the core functionality should work normally. For PG-specific extensions whose underlying mechanisms fundamentally conflict with Oracle compatibility mode and cannot run in this mode at all (for example, pg_partman, which is designed specifically to manage PostgreSQL partitioned tables and does not support running in Oracle compatibility mode), you must explain the situation in the adaptation document and the PR description. - -===== Compile and Install the Component - -Please refer to the target component's official documentation for compilation and installation. - -===== Test PG Mode - -Start an IvorySQL instance, connect to the database with psql through port 5432, and perform the following verifications: - -. Extension creation verification (only for extension-type components): run `CREATE EXTENSION` to confirm the extension can be created normally, and confirm the version matches expectations; -+ -[literal] ----- -ivorysql=# CREATE EXTENSION ; -ivorysql=# SELECT * FROM pg_available_extensions WHERE name = ''; ----- -+ -[NOTE] -Hook-type components loaded via `shared_preload_libraries` do not need this step; instead, confirm that after preloading the instance starts normally and the component's behavior takes effect. - -. Functionality testing: verify the core functionality item by item according to the test cases provided in the component documentation; -. Regression testing: if the component's source code ships with its own test cases, run them and ensure they all pass; -. Boundary testing: test boundary conditions and exception scenarios to confirm the component's robustness. - -If a certain function cannot be used or a test fails, investigate the cause: if it is an IvorySQL-side issue, open a PR against the IvorySQL repository to fix it; if it is a component-side issue, report it to the component's repository and record the limitation in the adaptation document. - -===== Test Oracle Compatibility Mode - -Connect to the database with psql through port 1521 (the Oracle compatibility port) and perform the following verifications: - -. Verify the component's main functionality following the same testing method as in PG mode; -. Test the component's data type compatibility in Oracle compatibility mode; -. Test whether the component's functionality supports Oracle-style anonymous blocks, stored procedures, functions, etc. - -Record whether each function is available in Oracle compatibility mode; this serves as the basis for the functional coverage statement in the adaptation document. - -Please note two things when testing: - -* *Write test statements using Oracle syntax.* Some syntax in Oracle compatibility mode differs from PG mode, so you cannot simply copy the PG-mode test cases. For example: the `interval` type must use Oracle-style syntax rather than PG syntax; statements such as `CREATE FUNCTION` and `CREATE PROCEDURE` must end with a `/` on its own line as the terminator. -* *Distinguish between "output differences" and "functional issues."* Some output that differs from PG mode is normal and should not be recorded as a compatibility issue. For example, type names in some output may carry a `pg_catalog.` schema prefix. To judge whether a function works normally, base it on whether the execution result is semantically correct, rather than requiring the output text to match the PG mode character for character. - -Record whether each function is available in Oracle compatibility mode; this serves as the basis for the functional coverage statement in the adaptation document. - -[NOTE] -Not all components can work in Oracle compatibility mode. If running `CREATE EXTENSION` or calling a component function fails due to a syntax error, it is usually because the component internally uses PG-specific syntax that Oracle does not support; please refer to the PG syntax whitelist mechanism in the next section to fix it. If the component fundamentally conflicts with Oracle compatibility mode at the underlying-mechanism level (such as pg_partman), you must clearly state this in the adaptation document and the PR description. - -===== Fix Compatibility Issues via the PG Syntax Whitelist - -A common reason why Oracle compatibility mode testing fails — especially when `CREATE EXTENSION` fails outright — is that the extension is implemented through SQL scripts that make heavy use of PG-specific syntax that Oracle does not support (such as PG-style `interval` expressions and array slicing), so the scripts cannot pass syntax parsing under Oracle compatibility mode. - -To address this, the IvorySQL kernel provides a PG syntax whitelist mechanism (see the `PgDialectExtensions` list in `src/backend/commands/extension.c`). After an extension is added to the whitelist, running `CREATE EXTENSION` in an Oracle compatibility mode cluster will: - -* Temporarily parse and execute the extension's install script with the PG parser, unaffected by the current session's compatibility mode; -* Automatically inject the `SET ivorysql.compatible_mode = pg` setting into the functions created by the install script, so that no matter which compatibility mode the calling session uses, the function body is always parsed and executed by the PG parser. - -With this mechanism, extensions implemented using PG-specific syntax can be installed and run normally in an Oracle compatibility mode cluster without modifying any code. The whitelist currently includes extensions such as pg_profile and pg_repack. - -This approach applies to: - -* Extensions that are mainly implemented in SQL or PL/pgSQL and fail `CREATE EXTENSION` or function calls in Oracle compatibility mode because they use PG-specific syntax; -* Extensions whose functionality is self-contained (such as management-type extensions for statistics collection, table reorganization, etc.), where users only call their entry functions and do not require their internal implementation to interact with Oracle-style objects. - -This approach does not apply to: - -* Extensions that need to interact deeply with user-created Oracle-style objects (stored procedures, Oracle-specific data types, etc.); forcing them to be parsed as PG syntax would break such interaction; -* Extensions that fundamentally conflict with Oracle compatibility mode at the underlying-mechanism level (such as pg_partman, which depends on PostgreSQL's native partitioned-table management). Such problems are not at the syntax-parsing level and cannot be solved by the whitelist; you must still state the limitation in the adaptation document and the PR description. - -Once you confirm that the target extension falls into the applicable scenario, you can open a PR against the IvorySQL repository to add the extension name to the `PgDialectExtensions` whitelist, and attach the test results from both modes in the PR description; at the same time, state in the "Oracle Compatibility" section of the adaptation document that the extension runs through the whitelist mechanism. - -==== Step 4: Documentation Writing - -==== Document Structure - -Each ecosystem component adaptation document should include the following sections (adjust as appropriate based on component characteristics): - -[cols="1,3"] -|=== -|Section |Description - -|Overview -|Introduce the component's functionality, use cases, and relationship with IvorySQL - -|Principle Introduction -|(Optional) Explain the component's core working principles to help readers understand how it works - -|Installation -|Detailed installation steps, including dependency installation, source acquisition, compilation, extension creation, etc. - -|Configuration -|If the component requires additional configuration steps (such as modifying `ivorysql.conf`, restarting services, etc.), explain them here - -|Usage -|Usage examples for core functionality, including object creation, operation execution, query results, etc. - -|Oracle Compatibility -|Component behavior in Oracle compatibility mode, including supported features and known limitations -|=== - -==== Document Template - -Below is a basic template for ecosystem component adaptation documentation. Contributors can fill in content based on this template: - -[source,asciidoc] ------- -:sectnums: -:sectnumlevels: 5 - -= - -== Overview - - -Project URL: - -Version: - -License: - -== Installation - -[TIP] -Source test installation environment is , with IvorySQL 5+ already installed at /usr/local/ivorysql/ivorysql-5 - -=== Dependencies - - -=== Source Installation -[literal] ----- -# Get source code -git clone -cd - -# Set pg_config path -export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config - -# Compile and install -make -sudo make install ----- - -=== Create Extension -[literal] ----- -ivorysql=# CREATE EXTENSION ; -CREATE EXTENSION - -ivorysql=# SELECT * FROM pg_available_extensions WHERE name = ''; ----- - -== Usage - -=== - - -=== - - -== Oracle Compatibility - ------- - -==== Update the Overview Page - -After completing the component documentation, please make sure to update the plugin list table in xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc] by appending a new row at the end of the table with the following information: - -* Index: Current maximum index + 1 -* Plugin name: Plugin name with xref link -* Version: The component version you adapted -* Function description: One-sentence summary of component functionality -* Use cases: List main use cases - -[NOTE] -Both the Chinese and English versions of the overview page need to be updated. - -==== Step 5: Submit PR - -===== Create Branch - -Ecosystem component adaptation documents are submitted to the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository (note: this is not the IvorySQL main repository where you create Issues). Please first fork the repository and clone it locally, then create a feature branch: - -[literal] ----- -git checkout -b feature/adapt- ----- - -===== Add Files - -. Place the documentation file in the `EN/modules/ROOT/pages/master/ecosystem_components/` directory -. If there are image resources, place them in the `EN/modules/ROOT/images/` directory -. Prepare the Chinese version simultaneously and place it in the corresponding CN directory -. Update the links in both the CN and EN `nav.adoc` and `ecosystem_overview.adoc` - -===== Create PR - -. Open a PR against the `master` branch of the https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] repository. -. Use `Fixes IvorySQL/IvorySQL#` in the PR description to link the adaptation Issue you claimed or created in Step 1 -. In the PR description, explain: -* The adapted component name and version -* Test environment information -* Completed test items -* Known limitations or issues - -[NOTE] -==== -. Since the Issue lives in the IvorySQL main repository, you must use the full reference format `IvorySQL/IvorySQL#`; once the PR is merged, the corresponding Issue is closed automatically. -. The linking keyword must be written in the PR description submitted to the IvorySQL docs repository and spelled correctly (`Fixes`/`Closes`/`Resolves` + a space + `IvorySQL/IvorySQL#`); writing it in a comment has no effect. -==== - -===== Await Review - -Maintainers will reproduce the test following the steps in the document and review the PR. They may suggest the following modifications: - -* Add missing test cases -* Fix documentation format issues -* Improve Oracle compatibility testing -* Add the Chinese translation - -Please revise and update the PR promptly based on review feedback. - -=== Frequently Asked Questions - -==== Compilation Error: Cannot Find pg_config - -Please confirm the `PG_CONFIG` environment variable is set correctly, pointing to `bin/pg_config` under the IvorySQL installation directory. You can verify with: - -[literal] ----- -$PG_CONFIG --version ----- - -==== Extension Creation Fails - -Please check: - -. Whether the extension's `.so` file is correctly installed in IvorySQL's `lib` directory -. Whether the extension's `.sql` and `.control` files are correctly installed in the `share/extension` directory -. Whether the IvorySQL version is compatible with the PostgreSQL version required by the component -. If the failure is caused by PG-specific syntax that cannot be parsed, refer to the PG syntax whitelist mechanism in Step 3. - -==== Functionality Issues in Oracle Compatibility Mode - -Some PostgreSQL extensions rely on the native PG parser and may not work correctly in Oracle compatibility mode. When encountering such issues, clearly state the limitations in the document's "Oracle Compatibility" section and provide alternative solutions if available. - -==== Unsure Whether a Component Is Suitable for Adaptation - -Please start a discussion in https://github.com/IvorySQL/IvorySQL/issues[Issues], describing the component's functionality and your adaptation plan. Maintainers will provide an assessment. - -== Acknowledgments - -Thank you to every developer, documentation editor, tester, and user who participates in IvorySQL. It is because of your efforts that IvorySQL can continue to grow! We welcome everyone to participate in IvorySQL community contributions. Our goal is to develop an active, healthy community of contributors. From 6ffb236ac650032beeeab46eb63d74cfa072c9b6 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 15:20:41 +0800 Subject: [PATCH 08/10] docs: fix broken links in contribution guide Fixed several problematic links in the Chinese contribution guide: - Line 43: Changed self-referencing xref to internal anchor reference - Line 294: Fixed malformed link in section title - Lines 336, 347: Removed malformed placeholder links with $user variables All links now point to valid targets or have been simplified to plain text where appropriate. --- .../pages/master/contribution/contribution_guide.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index a97f3ff..97c41fd 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -40,7 +40,7 @@ IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvoryS * 发现 Bug、性能缺陷或文档不准确？ * 有新的功能建议或使用体验改进？ -如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考 Issue xref:master/contribution/contribution_guide.adoc[提交指南]。 +如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考本指南的 xref:#_提_issue[提交 Issue] 章节。 ==== 参与社区讨论 @@ -291,7 +291,7 @@ Title: 标题 == **贡献代码** -=== 第1步: Fork https://ivorysql.org/[ivorysql.org]仓库 +=== 第1步: Fork IvorySQL 仓库 1、打开ivorysql仓库 https://github.com/IvorySQL/IvorySQL @@ -333,7 +333,7 @@ Git push -u origin new-branch-name === 第7步：创建一个Pull Request -1、打开你 Fork 的仓库： https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL]（将 $user 替换为你的 GitHub ID）。 +1、打开你 Fork 的仓库（将 $user 替换为你的 GitHub ID）。 2、点击 Compare & pull request 按钮即可创建 PR。 @@ -344,7 +344,7 @@ Git push -u origin new-branch-name === 第1步：创建一个Pull Request -1、打开你 Fork 的仓库： https://github.com/$user/docs-cn[https://github.com/$user/IvorySQL]（将 $user 替换为你的 GitHub ID）。 +1、打开你 Fork 的仓库（将 $user 替换为你的 GitHub ID）。 ​ 2、点击 Compare & pull request 按钮 From 7304d6aebcb07e34ee00b3a99b0e1190fa2fc6b3 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 15:44:33 +0800 Subject: [PATCH 09/10] docs: fix broken links and update references in contribution guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Line 43: Changed xref link to plain text '提交 Issue' - Lines 112-113: Updated CLA file URLs to new addresses - Line 160: Changed xref link to plain text '生态组件适配' - Line 164: Removed GitHub URL - Line 166: Added AtomGit URL (https://atomgit.com/IvorySQL/IvorySQL) - Line 167: Removed 码云 URL - Line 181: Changed email to proper mailto link - Line 915: Fixed source repository URL format - Lines 924, 946: Changed internal references to plain text - Line 1097: Changed internal reference to plain text - Line 1144: Changed xref link to plain text '签署 CLA' All problematic links have been fixed or converted to plain text where appropriate. --- .../contribution/contribution_guide.adoc | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 97c41fd..39f4c5f 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -40,7 +40,7 @@ IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvoryS * 发现 Bug、性能缺陷或文档不准确？ * 有新的功能建议或使用体验改进？ -如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考本指南的 xref:#_提_issue[提交 Issue] 章节。 +如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考本指南的"提交 Issue"章节。 ==== 参与社区讨论 @@ -109,8 +109,8 @@ IvorySQL 源码托管在 GitHub：。 在提交代码或文档贡献之前，为了确保代码合法合规，个人或企业贡献者需要签署贡献者许可协议（CLA）。签署 CLA 是 IvorySQL 社区接受贡献的必要条件，以确保您的贡献被合法分发。请根据下列链接下载 CLA 进行签署并将签署后的 CLA 发送至 cla@ivorysql.org。 -* https://www.ivorysql.org/zh-CN/assets/files/individual_cla-a81f001209eb5ce0f8ea7c3be4cc69b5.pdf[个人贡献者] -* https://www.ivorysql.org/zh-CN/assets/files/corporate_cla-76e89b6f17b0bc102cbc1105d438a917.pdf[企业贡献者] +* https://www.ivorysql.org/zh-cn/assets/files/individual_cla-7703700da5e1ca8f26cb8a68f610d4f2.pdf[个人贡献者] +* https://www.ivorysql.org/zh-cn/assets/files/corporate_cla-88aa01a7e770ecf89dc401f925c3438e.pdf[企业贡献者] 未签署 CLA 的 Pull Request 将无法进入评审阶段。 @@ -157,13 +157,14 @@ IvorySQL社区提供的是中英文文档。英文文档保存在...文档存储 IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 -适配工作主要包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档。详细步骤请参考 xref:#_生态组件适配_2[生态组件适配] 章节。 +适配工作主要包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档。详细步骤请参考"生态组件适配"章节。 ==== 测试IvorySQL和报告问题 -GitHub: https://github.com/IvorySQL/IvorySQL +GitHub -​码云：https://gitee.com/IvorySQL/ +AtomGit：https://atomgit.com/IvorySQL/IvorySQL +​码云 ==== 参与IvorySQL网站建设 @@ -177,7 +178,7 @@ IvorySQL官网下载：https://github.com/IvorySQL/Ivory-www ==== 贡献文章 -您可以在IvorySQL-WWW代码仓库自己提交至blog贡献，也可以联系我们IvorySQL小助理发送至邮箱ivorysql@highgo.com 。 +您可以在IvorySQL-WWW代码仓库自己提交至blog贡献，也可以联系我们IvorySQL小助理发送至邮箱 mailto:ivorysql@highgo.com[ivorysql@highgo.com] 。 === 如何做出贡献 @@ -911,7 +912,7 @@ image::17.png[] 1、下载 https://markdown.com.cn/tools.html#%E7%BC%96%E8%BE%91%E5%99%A8[Markdown]或者 https://typoraio.cn/[Typora]文档编辑器。 -​ 2、先下载博客源码到本地，检查源仓库(https://github.com/IvorySQL/Ivory-www)是否有更新， 如果有更新请先更新并同步到自己的仓库。请参阅以下步骤，更新至最新版本： +​ 2、先下载博客源码到本地，检查源仓库 https://github.com/IvorySQL/Ivory-www 是否有更新，如果有更新请先更新并同步到自己的仓库。请参阅以下步骤，更新至最新版本： ``` bash # 拉取网站源码 @@ -920,7 +921,7 @@ git clone https://github.com/IvorySQL/Ivory-www.git git pull ``` -​ 3、熟悉样式风格 (<<#_规范说明_2>>) +​ 3、熟悉样式风格（规范说明） === 贡献地方 @@ -942,7 +943,7 @@ git clone https://github.com/IvorySQL/Ivory-www.git git checkout -b ``` -​ （3）在博客目录中创建自己文章的目录，目录名字规则参照 (<<#_规范说明_2>>)。 +​ （3）在博客目录中创建自己文章的目录，目录名字规则参照规范说明。 ```bash # 生成英文博客目录及文件 @@ -1093,7 +1094,7 @@ image::13.png[] 如果您不满足于简单的在网页端进行提交或者仅修改网页内容，又或者您想要修改网页ui，本小节内容将会帮助到您。 -在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考<<#_如何贡献>>。 +在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考"如何贡献"章节。 === 部署网页 @@ -1141,7 +1142,7 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 ===== 签署 CLA -在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的 xref:#_签署_cla[签署 CLA] 章节。 +在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的"签署 CLA"章节。 ==== 第二步：环境准备 From 7dbcac3f166b7842875e3005ef42c84dcc83b412 Mon Sep 17 00:00:00 2001 From: JiaoShuntian Date: Mon, 20 Jul 2026 15:49:28 +0800 Subject: [PATCH 10/10] docs: convert remaining section references to plain text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert all internal section references with '章节' suffix to plain text format: - Line 43: '提交 Issue'章节 → 提交 Issue - Line 160: '生态组件适配'章节 → 生态组件适配 - Line 1145: '签署 CLA'章节 → 签署 CLA All section references are now in plain text format without quotes or '章节' suffix. --- .../pages/master/contribution/contribution_guide.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 39f4c5f..1cf772d 100644 --- a/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -40,7 +40,7 @@ IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvoryS * 发现 Bug、性能缺陷或文档不准确？ * 有新的功能建议或使用体验改进？ -如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考本指南的"提交 Issue"章节。 +如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考本指南的提交 Issue。 ==== 参与社区讨论 @@ -157,7 +157,7 @@ IvorySQL社区提供的是中英文文档。英文文档保存在...文档存储 IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 -适配工作主要包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档。详细步骤请参考"生态组件适配"章节。 +适配工作主要包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档。详细步骤请参考生态组件适配。 ==== 测试IvorySQL和报告问题 @@ -1094,7 +1094,7 @@ image::13.png[] 如果您不满足于简单的在网页端进行提交或者仅修改网页内容，又或者您想要修改网页ui，本小节内容将会帮助到您。 -在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考"如何贡献"章节。 +在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考如何贡献。 === 部署网页 @@ -1142,7 +1142,7 @@ IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然 ===== 签署 CLA -在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的"签署 CLA"章节。 +在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的签署 CLA。 ==== 第二步：环境准备