diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 991c4af..4d274a5 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -80,7 +80,7 @@ * 数据迁移 ** xref:master/migration_guide.adoc[迁移指南] * IvorySQL开发者 -** xref:master/contribution/community_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/issue_submission_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc similarity index 59% rename from CN/modules/ROOT/pages/master/contribution/issue_submission_guide.adoc rename to CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc index 908c195..1cf772d 100644 --- a/CN/modules/ROOT/pages/master/contribution/issue_submission_guide.adoc +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -27,6 +27,93 @@ IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvoryS ​ 责任：提交者/维护者有权合并拉取请求，因此承担额外的责任来处理接受代码库或文档更改的后果。这包括在它导致问题时恢复或修复它，以及帮助发布经理解决发布前测试周期中发现的任何问题。 +== 角色与职责 + +在参与贡献前，请确认您当前的参与身份，以便更高效地了解适合您的贡献方式： + +=== 用户 + +作为用户，您在使用 IvorySQL 过程中扮演着重要角色。我们鼓励您： + +==== 反馈问题与需求 + +* 发现 Bug、性能缺陷或文档不准确？ +* 有新的功能建议或使用体验改进？ + +如果您准备向社区上报 Bug 或者提交需求，请在 IvorySQL 社区对应的仓库上提交 Issue，并参考本指南的提交 Issue。 + +==== 参与社区讨论 + +* 通过 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-7703700da5e1ca8f26cb8a68f610d4f2.pdf[个人贡献者] +* https://www.ivorysql.org/zh-cn/assets/files/corporate_cla-88aa01a7e770ecf89dc401f925c3438e.pdf[企业贡献者] + +未签署 CLA 的 Pull Request 将无法进入评审阶段。 + == **贡献者指南** 在贡献之前，我们需要了解下IvorySQL目前的版本以及文档的版本。目前，我们维护着5.0等版本，我们的版本紧跟PG的更新步伐，贡献之前请更新至最新版本。之后我们需要细心浏览一下贡献的样式风格，熟悉代码贡献风格、提Issue样式、拉取PR标题样式、代码注释样式、文档贡献样式、文章贡献样式，这可以帮助您尽快成为IvorySQL的贡献者奥~。 @@ -66,11 +153,18 @@ IvorySQL是在GitHub上开发的，任何希望对其作出贡献的人都必须 IvorySQL社区提供的是中英文文档。英文文档保存在...文档存储库中，中文文档保存在i18n文档存储库中。您可以为任一文档存储库做出贡献。 +==== 生态组件适配 + +IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 + +适配工作主要包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档。详细步骤请参考生态组件适配。 + ==== 测试IvorySQL和报告问题 -GitHub: https://github.com/IvorySQL/IvorySQL +GitHub -​码云：https://gitee.com/IvorySQL/ +AtomGit：https://atomgit.com/IvorySQL/IvorySQL +​码云 ==== 参与IvorySQL网站建设 @@ -84,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] 。 === 如何做出贡献 @@ -198,7 +292,7 @@ Title: 标题 == **贡献代码** -=== 第1步: Fork https://ivorysql.org/[ivorysql.org]仓库 +=== 第1步: Fork IvorySQL 仓库 1、打开ivorysql仓库 https://github.com/IvorySQL/IvorySQL @@ -240,7 +334,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。 @@ -251,7 +345,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 按钮 @@ -818,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 # 拉取网站源码 @@ -827,7 +921,7 @@ git clone https://github.com/IvorySQL/Ivory-www.git git pull ``` -​ 3、熟悉样式风格 (<<#_规范说明_2>>) +​ 3、熟悉样式风格（规范说明） === 贡献地方 @@ -849,7 +943,7 @@ git clone https://github.com/IvorySQL/Ivory-www.git git checkout -b ``` -​ （3）在博客目录中创建自己文章的目录，目录名字规则参照 (<<#_规范说明_2>>)。 +​ （3）在博客目录中创建自己文章的目录，目录名字规则参照规范说明。 ```bash # 生成英文博客目录及文件 @@ -1000,7 +1094,7 @@ image::13.png[] 如果您不满足于简单的在网页端进行提交或者仅修改网页内容，又或者您想要修改网页ui，本小节内容将会帮助到您。 -在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考<<#_如何贡献>>。 +在阅读本小节内容之前，您需要确认您的Github个人仓库是否已经 `fork` 了网页模板文件仓库和静态网页文件仓库，如果没有请参考如何贡献。 === 部署网页 @@ -1010,3 +1104,320 @@ image::13.png[] 本章节主要介绍了如何自己主动去更新我们的文档中心，但是我们明确地知道山高路远，时不我待。因此对于没有太多时间的小伙伴来说，可以发邮件到我们的 **ivorysql-docs@ivorysql.org**，我们会有专门的工作人员进行处理您的每一封来信，期待您的邮件。 +== 生态组件适配 + +IvorySQL 作为一款基于 PostgreSQL 研发的 Oracle 兼容数据库，天然继承了 PostgreSQL 丰富的扩展生态。为了让更多的 PostgreSQL 生态组件能够在 IvorySQL 上稳定运行，IvorySQL 社区欢迎外部贡献者参与生态组件的适配工作。 + +=== 适配范围 + +以下类型的组件欢迎贡献者进行适配： + +* PostgreSQL 社区官方扩展（contrib 模块） +* 基于 PostgreSQL 扩展机制开发的第三方插件 +* 以独立进程形式与数据库配合工作的周边生态工具，如连接池、代理、中间件等 + +=== 贡献流程 + +生态组件适配，是将 PostgreSQL 生态组件适配到 IvorySQL 的工作。主要内容包括：了解目标组件的特点、原理和使用方式，测试其在 IvorySQL 的 PG 模式和 Oracle 兼容模式下能否正常使用；最后基于上述调研与测试结果，编写一篇生态组件适配文档，提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库。文档提交后，维护者会按照适配文档中给出的步骤对目标组件进行复现测试，确认测试结果与文档描述一致后，合并该 PR。 + +具体的选题、测试、文档编写等环节，请参考下面的详细步骤。 + +==== 第一步：选题与沟通 + +===== 确认组件未被适配 + +在开始适配工作之前，请先查阅 xref:master/ecosystem_components/ecosystem_overview.adoc[生态组件适配列表]，确认目标组件是否已完成适配。如果目标组件不在列表中，则继续后面的流程；否则，请重新选择一个未适配的组件。 + +===== 认领或新建 Issue + +在 IvorySQL 仓库的 https://github.com/IvorySQL/IvorySQL/issues[Issue 列表] 中搜索目标组件： + +- 如果相关适配 Issue 已存在，先确认其尚未被分配（Assignees 为空），然后点击右上角 Assignees 区域的 `Assign yourself`，将该 Issue 认领给自己；若已被他人认领，请重新选择组件； +- 如果相关 Issue 尚不存在，则新建一个 `Feature Request` 类型的 Issue，添加 `compatibility` 标签，并分配给自己。新建 Issue 的格式可参考已有的生态组件适配类 Issue：标题格式为 `Ecosystem Integration: <组件名>`，正文用一句话说明要适配的组件及其用途。 + +维护者会评估该组件是否适合纳入 IvorySQL 生态，并在 Issue 中与您沟通确认。 + +[TIP] +建议在 Issue 获得维护者确认后再开始适配工作，避免重复或无效工作。 + +===== 签署 CLA + +在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的签署 CLA。 + +==== 第二步：环境准备 + +===== IvorySQL 环境 + +请准备一套可用于测试的 IvorySQL 环境，建议满足以下要求： + +* IvorySQL 版本：5.0 及以上 +* 操作系统：建议使用 Ubuntu 24.04 (x86_64) 或其他主流 Linux 发行版 +* 安装路径：记录 IvorySQL 的安装路径，后续编译扩展时需要用到 `pg_config` 的路径 + +[TIP] +可以通过 IvorySQL 官方提供的 Docker 镜像快速搭建测试环境，参考 xref:master/containerization/docker_podman_deployment.adoc[Docker & Podman 部署]。 + +===== 编译工具链 + +根据目标组件的编译方式，准备相应的工具链： + +* C/C++ 扩展：需要 gcc、make 等基础编译工具 +* Rust 扩展：需要 cargo、rustc 等 Rust 工具链 +* 其他语言扩展：需要对应语言的运行环境 + +==== 第三步：适配测试 + +生态组件适配的目标分为两个层面： + +- PG 模式：组件必须完全可用。 +- Oracle 兼容模式：应尽可能做到完全可用；若无法完全可用，至少应保证主要功能可以正常运行。对于底层机制与 Oracle 兼容模式冲突、完全无法在该模式下运行的 PG 专用扩展（例如 pg_partman 专为管理 PostgreSQL 分区表而设计，不支持在 Oracle 兼容模式下运行），需在适配文档和 PR 描述中说明情况。 + +===== 组件编译安装 + +请参考目标组件的官方文档进行编译安装。 + +===== 测试 PG 模式 + +启动 IvorySQL 实例，使用 psql 通过 5432 端口连接数据库，进行以下验证： + +. 扩展创建验证（仅适用于扩展类组件）：执行 `CREATE EXTENSION` 确认扩展可以正常创建，并确认版本与预期一致； ++ +[literal] +---- +ivorysql=# CREATE EXTENSION <扩展名>; +ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; +---- ++ +[NOTE] +通过 `shared_preload_libraries` 加载的钩子类组件无需此步骤，改为确认预加载后实例正常启动、组件行为生效。 + +. 功能测试：根据组件文档提供的功能用例，逐一验证核心功能是否正常工作； +. 回归测试：如果组件源码自带测试用例，应运行并确保其全部通过； +. 边界测试：测试边界条件和异常场景，确认组件的健壮性。 + +如果某个功能无法使用或测试失败，需排查原因：属于 IvorySQL 侧的问题，请向 IvorySQL 仓库提交 PR 修复；属于组件侧的问题，可向组件仓库反馈，并在适配文档中记录该限制。 + +===== 测试 Oracle 兼容模式 + +使用 psql 通过 1521 端口（Oracle 兼容端口）连接数据库，进行以下验证： + +. 参照 PG 模式的测试方法验证组件的主要功能； +. 测试组件在 Oracle 兼容模式下的数据类型兼容性； +. 测试组件功能是否支持 Oracle 风格的匿名块、存储过程、函数等。 + +记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。 + +测试时请注意以下两点： + +* *使用 Oracle 语法编写测试语句*。Oracle 兼容模式下的部分语法与 PG 模式不同，不能直接照搬 PG 模式的测试用例。例如：interval 类型需使用 Oracle 风格的语法，而非 PG 语法；`CREATE FUNCTION`、`CREATE PROCEDURE` 等语句需在末尾另起一行加 `/` 作为结束符。 +* *区分"输出差异"与"功能异常"*。部分输出与 PG 模式不一致属于正常现象，不应记为兼容性问题。例如：某些输出中的类型名会带有 `pg_catalog.` 模式前缀。判断功能是否正常，应以执行结果的语义是否正确为准，而不要求输出文本与 PG 模式逐字一致。 + +记录各功能在 Oracle 兼容模式下是否可用，作为适配文档中功能覆盖说明的依据。 + +[NOTE] +并非所有组件都能在 Oracle 兼容模式下工作。如果执行 `CREATE EXTENSION` 或调用组件功能时因语法错误而失败，多是组件内部使用了 Oracle 不支持的 PG 专用语法所致，请参考下一节的 PG 语法白名单机制进行修复；如果组件与 Oracle 兼容模式在底层机制上冲突（如 pg_partman），则需要在适配文档和 PR 描述中明确说明。 + +===== 通过 PG 语法白名单修复兼容问题 + +Oracle 兼容模式测试不通过——尤其是执行 `CREATE EXTENSION` 就直接失败——的一个常见原因是：扩展通过 SQL 脚本实现，脚本中大量使用了 Oracle 不支持的 PG 专用语法（如 PG 风格的 interval 表达式、数组切片等），导致脚本无法通过 Oracle 兼容模式下的语法解析。 + +针对这种情况，IvorySQL 内核提供了 PG 语法白名单机制（见 `src/backend/commands/extension.c` 中的 `PgDialectExtensions` 列表）。扩展加入白名单后，在 Oracle 兼容模式集群中执行 `CREATE EXTENSION` 时： + +* 扩展的安装脚本会临时改用 PG 解析器解析执行，不受当前会话兼容模式的影响； +* 安装脚本所创建的函数会被自动注入 `SET ivorysql.compatible_mode = pg` 配置，此后无论从哪种兼容模式的会话调用，函数体都由 PG 解析器解析执行。 + +借助该机制，使用 PG 专用语法实现的扩展无需修改任何代码，即可在 Oracle 兼容模式集群中正常安装和运行。目前白名单中已包含 pg_profile、pg_repack 等扩展。 + +该方式适用于： + +* 扩展主要通过 SQL 或 PL/pgSQL 实现，因使用 PG 专用语法导致 `CREATE EXTENSION` 或函数调用在 Oracle 兼容模式下失败； +* 扩展功能自成一体（如统计信息采集、表重组等管理类扩展），用户只需调用其入口函数，不要求其内部实现与 Oracle 风格对象交互。 + +该方式不适用于： + +* 扩展需要与用户创建的 Oracle 风格对象（存储过程、Oracle 专有数据类型等）深度交互，强制按 PG 语法解析会破坏这种交互； +* 扩展与 Oracle 兼容模式在底层机制上冲突（如 pg_partman 依赖 PostgreSQL 原生的分区表管理），此类问题不在语法解析层面，白名单无法解决，仍需在适配文档和 PR 描述中说明限制。 + +确认目标扩展属于适用场景后，您可以向 IvorySQL 仓库提交 PR，将扩展名加入 `PgDialectExtensions` 白名单，并在 PR 描述中附上两种模式下的测试结果；同时在适配文档的 "Oracle 兼容性" 章节中说明该扩展通过白名单机制运行。 + +==== 第四步：文档编写 + +IvorySQL 文档使用 AsciiDoc 编写的，其语法与 Markdown 类似但功能更加强大。如果不熟悉 AsciiDoc 语法，可参阅 xref:master/contribution/asciidoc_syntax_reference.adoc[asciidoc语法快速参考]。 + +===== 文档结构 + +每篇生态组件适配文档应包含以下章节（可根据组件特点适当调整）： + +[cols="1,3"] +|=== +|章节 |说明 + +|概述 +|介绍组件的功能、适用场景，以及与 IvorySQL 的关系 + +|原理介绍 +|（可选）介绍组件的核心工作原理，帮助读者理解组件的运作机制 + +|安装 +|详细的安装步骤，包括依赖安装、源码获取、编译安装、扩展创建等 + +|配置 +|如果组件需要额外的配置步骤（如修改 `ivorysql.conf`、重启服务等），在此说明 + +|使用 +|核心功能的使用示例，包括创建对象、执行操作、查询结果等 + +|Oracle 兼容性 +|组件在 Oracle 兼容模式下的表现，包括支持的功能和已知限制 +|=== + +===== 文档模板 + +以下是一个生态组件适配文档的基础模板，贡献者可以在此基础上填充内容： + +[source,asciidoc] +------ +:sectnums: +:sectnumlevels: 5 + += <组件名称> + +== 概述 +<组件功能介绍、适用场景、与 IvorySQL 的关系> + +项目地址： + +版本：<适配的组件版本号> + +开源协议：<组件的开源协议> + +== 安装 + +[TIP] +源码测试安装环境为 <操作系统版本>，环境中已安装 IvorySQL 5 及以上版本，安装路径为 /usr/local/ivorysql/ivorysql-5 + +=== 依赖 +<列出并说明安装所需的依赖> + +=== 源码安装 +[literal] +---- +# 获取源码 +git clone <仓库地址> +cd <目录> + +# 设置 pg_config 路径 +export PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config + +# 编译安装 +make +sudo make install +---- + +=== 创建扩展 +[literal] +---- +ivorysql=# CREATE EXTENSION <扩展名>; +CREATE EXTENSION + +ivorysql=# SELECT * FROM pg_available_extensions WHERE name = '<扩展名>'; +---- + +== 使用 + +=== <功能点一> +<使用示例及输出> + +=== <功能点二> +<使用示例及输出> + +== Oracle 兼容性 +<可选：在 Oracle 兼容模式下的测试结果> +------ + +===== 同步更新概述页 + +完成组件文档编写后，请务必同步更新 xref:master/ecosystem_components/ecosystem_overview.adoc[ecosystem_overview.adoc] 中的插件列表表格，在表格末尾追加一行新记录，包含以下信息： + +* 序号：当前最大序号加 1 +* 插件名称：带 xref 链接的插件名称 +* 版本：您适配的组件版本 +* 功能描述：一句话概括组件功能 +* 适用场景：列举主要适用场景 + +[NOTE] +中英文版本的概述页都需要同步更新。 + +==== 第五步：提交 PR + +===== 创建分支 + +生态组件适配文档统一提交到 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库（注意：不是创建 Issue 的 IvorySQL 主仓库）。请先 fork 该仓库并 clone 到本地，然后创建特性分支： + +[literal] +---- +git checkout -b feature/adapt-<组件名称> +---- + +===== 添加文件 + +. 将文档文件放入 `CN/modules/ROOT/pages/master/ecosystem_components/` 目录 +. 如有图片资源，放入 `CN/modules/ROOT/images/` 目录 +. 同步准备英文版本，放入对应的 EN 目录 +. 更新 CN 和 EN 的 `nav.adoc` 和 `ecosystem_overview.adoc` 里的链接 + +===== 创建 PR + +. 向 https://github.com/IvorySQL/ivorysql_docs[IvorySQL docs] 仓库的 master 分支提交 PR +. 在 PR 描述中使用 `Fixes IvorySQL/IvorySQL#<编号>` 关联第一步中认领或新建的适配 Issue +. 在 PR 描述中说明： +* 适配的组件名称和版本 +* 测试环境信息 +* 已完成的测试项目 +* 已知的限制或问题 + +[NOTE] +==== +. 由于 Issue 位于 IvorySQL 主仓库，必须使用 `IvorySQL/IvorySQL#编号` 的完整引用格式；PR 合并后，对应 Issue 会被自动关闭。 +. 关联关键字必须写在 IvorySQL docs 仓库提交的 PR 描述中且拼写规范（`Fixes`/`Closes`/`Resolves` + 空格 + `IvorySQL/IvorySQL#<编号>`），写在评论里无效。 +==== + +===== 等待评审 + +维护者会按照文档中的步骤复现测试，并对 PR 进行评审，可能会提出以下修改建议： + +* 补充缺失的测试用例 +* 修正文档格式问题 +* 完善 Oracle 兼容性测试 +* 补充英文版翻译 + +请根据评审意见及时修改并更新 PR。 + +=== 常见问题 + +==== 编译报错找不到 pg_config + +请确认 `PG_CONFIG` 环境变量设置正确，指向 IvorySQL 安装目录下的 `bin/pg_config`。可以通过以下命令确认： + +[literal] +---- +$PG_CONFIG --version +---- + +==== 扩展创建失败 + +请检查： + +. 扩展的 `.so` 文件是否正确安装到 IvorySQL 的 `lib` 目录 +. 扩展的 `.sql` 和 `.control` 文件是否正确安装到 `share/extension` 目录 +. IvorySQL 版本是否与组件要求的 PostgreSQL 版本兼容 +. 若失败原因是 PG 专用语法无法解析，可参考第三步的 PG 语法白名单机制。 + +==== Oracle 兼容模式下功能异常 + +部分 PostgreSQL 扩展依赖 PG 原生解析器，在 Oracle 兼容模式下可能无法正常工作。遇到此类问题时，请在文档的 "Oracle 兼容性" 章节中明确说明限制，并提供替代方案（如有）。 + +==== 不确定组件是否适合适配 + +请先在 https://github.com/IvorySQL/IvorySQL/issues[Issues] 中发起讨论，描述组件的功能和您的适配计划，维护者会给出评估意见。 + diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index b071b69..d295068 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -80,8 +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] * 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.