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/contribution_guide.adoc b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc new file mode 100644 index 0000000..60bd697 --- /dev/null +++ b/CN/modules/ROOT/pages/master/contribution/contribution_guide.adoc @@ -0,0 +1,650 @@ + +:sectnums: +:sectnumlevels: 5 + +:imagesdir: ./_images += **IvorySQL社区贡献指南** + +== **概述** + +=== 说明 + +IvorySQL由一个核心开发团队维护，该团队拥有对GitHub上的IvorySQL主存储库的提交权限。同时，我们非常渴望从更广泛的IvorySQL社区中的成员那里获得贡献。如果您希望看到您的代码或文档更改被添加到IvorySQL并出现在将来的版本中，本节的内容介绍是您需要知道的。 + +​IvorySQL社区欢迎并赞赏所有类型的贡献，期待您的加入！ + +=== 行为准则 + +作为成员，贡献者和领导者，我们每个人都应阅读我们的 *行为准则*。我们承诺让每个人都能参与社区，成为一种无骚扰的体验，无论年龄、体型、有形或无形的残疾、种族、性特征、性别认同和表达、经验水平、教育、社会经济地位、国籍、个人外表、种族、宗教或性身份和取向如何。 + +​ 我们承诺以有助于建立一个开放，热情，多样化，包容和健康社区的方式采取行动和互动。 + +=== 管理说明 + +团队是持续开放的团队，专注于IvorySQL项目的一部分。一个团队有其审查者、提交者和维护者，并拥有一个或多个存储库。团队级别的决策来自其维护者。IvorySQL开发人员的典型提升路径是从用户到审查者，然后是提交者和维护者。但获得更多的角色并不意味着你对其他社区成员拥有任何特权。IvorySQL社区中的每个人都是平等的，都有责任与其他贡献者进行建设性合作，建立一个友好的社区。这些角色是对您在IvorySQL开发中做出重大贡献的自然奖励，并为您在开发工作流中提供更多权利，以提高您的效率。同时，他们要求你承担一些额外的责任： + +​ 团队荣誉：现在您已经是团队评审员/提交者/维护者的成员，意味着您代表着项目和您的团队成员。所以，请做一个好人来捍卫球队的声誉。 + +​ 责任：提交者/维护者有权合并拉取请求，因此承担额外的责任来处理接受代码库或文档更改的后果。这包括在它导致问题时恢复或修复它，以及帮助发布经理解决发布前测试周期中发现的任何问题。 + +== 角色与职责 + +在参与贡献前，请确认您当前的参与身份，以便更高效地了解适合您的贡献方式： + +=== 用户 + +作为用户，您在使用 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 将无法进入评审阶段。 + + +== **提交Issue** + +=== 进入New issue 页面： + +1、进入 IvorySql官网：https://github.com/IvorySQL/IvorySQL + +​2、点击New issue + +image::p3.png[] + + +=== 选择需要填写的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 +描述你期望实现的一个功能 +``` + + +=== 提交 + +点击 submit new issue 按钮, 提交即可 + +== **提交PR** + +对于提交一个PR应该保持一个功能，或者一个bug提交一次。禁止多个功能一次提交。 + + +=== 创建一个Pull Request + +1、打开你 Fork 的仓库（将 $user 替换为你的 GitHub ID）。 + + 2、点击 Compare & pull request 按钮 + +=== 填写PR信息 + +``` +Fix test +功能描述 +``` + +``` +leave a comment +对该提交功能进行比较详细的描述 +``` + +=== 提交PR + +点击Create pull request 按钮即可提交。 + +== **代码贡献** + +=== Fork IvorySQL 仓库 + +1、打开ivorysql仓库 https://github.com/IvorySQL/IvorySQL + +2、点击右上角fork按钮，等待fork完成 + +=== 将fork的仓库克隆至本地 + +``` +cd $working_dir # 将 $working_dir 替换为你想放置 repo 的目录。例如，`cd ~/Documents/GitHub` + +git clone git@github.com:$user/IvorySQL.git # 将 `$user` 替换为你的 GitHub ID +``` + +=== 创建一个新的Branch + +``` +cd $working_dir/IvorySQL + +git checkout -b new-branch-name +``` + +=== 修改代码 + +在新建的new-branch-name中修改代码。 + +=== 生成commit + +``` +Git add + +Git commit -m “commit-message” +``` + +=== 将修改推送至远端 + +``` +Git push -u origin new-branch-name +``` + +完成代码推送后，请参考 xref:#_提交_pr[提交 PR] 章节创建 Pull Request。 + +== **文档贡献** + +IvorySQL 社区提供双语文档。英文文档保存在 EN/ 目录中，中文文档保存在 CN/ 目录中。您可以为任何一方文档做出贡献，当然您也可以为两方同时做出贡献。文档贡献遵循"fork - pull request - merge"流程。 + +=== 文档中心结构 + +IvorySQL 文档中心由三部分组成： + +* https://github.com/IvorySQL/ivorysql_docs[文档文件]：存放所有 AsciiDoc 格式的源文件 +* https://github.com/IvorySQL/ivorysql_web[静态网页文件]：存放生成的静态网页 +* https://github.com/IvorySQL/ivory-doc-builder[网页模板文件]：用于生成网页的模板和配置 + +如果您只是想修改现有内容或添加新页面，只需要 fork 文档文件仓库即可。如果想深度参与文档中心建设（如修改网页 UI），则需要同时 fork 这三个仓库。 + +=== 贡献方式 + +您可以从以下任何一项开始，以帮助改进 IvorySQL 文档： + +* 编写完善文档 +* 修复拼写错误或格式（标点符号、空格、缩进、代码块等） +* 修正或更新不当或过时的说明 +* 添加缺少的内容（句子、段落或新文档） +* 将文档更改从英文翻译成中文，或从中文翻译成英文 +* 提交、回复和解决文档问题 +* （高级）查看其他人创建的拉取请求 + +=== 方式一：通过网站快速编辑（适合小修改） + +对于简单的修改（如修复拼写错误、更新 small 内容），可以直接通过网站进行： + +. 在文档页面右上角点击 `Edit this page` 按钮 +. 系统会跳转到 GitHub 上对应源文件的编辑页面 +. 按照 AsciiDoc 格式修改内容 +. 填写修改说明后提交 PR + +这种方式无需本地环境，适合快速修正小问题。 + +=== 方式二：完整 Git 工作流（适合较大改动） + +对于较大的改动或添加新页面，建议使用完整的 Git 工作流： + +==== Fork 文档仓库 + +1、打开文档仓库 https://github.com/IvorySQL/ivorysql_docs + +2、点击右上角 fork 按钮，等待 fork 完成 + +==== 将 fork 的仓库克隆至本地 + +``` +cd $working_dir # 将 $working_dir 替换为你想放置 repo 的目录 + +git clone git@github.com:$user/ivorysql_docs.git # 将 `$user` 替换为你的 GitHub ID +``` + +==== 创建一个新的 Branch + +``` +cd $working_dir/ivorysql_docs + +git checkout -b new-branch-name +``` + +==== 编辑文档 + +在新建的 new-branch-name 中编辑文档。IvorySQL 文档使用 AsciiDoc 格式编写，请参考 xref:master/contribution/asciidoc_syntax_reference.adoc[AsciiDoc 语法参考]。 + +添加新页面时： +. 将 `.adoc` 文件放入正确目录（CN/ 或 EN/ 对应版本目录） +. 中英文文件应该同名 +. 修改对应的 `nav.adoc` 文件添加导航链接 + +==== 生成 commit + +``` +git add + +git commit -m "commit-message" +``` + +==== 将修改推送至远端 + +``` +git push -u origin new-branch-name +``` + +完成文档推送后，请参考 xref:#_提交_pr[提交 PR] 章节创建 Pull Request。 + +提交 PR 后，系统会自动在 PR 页面生成预览地址。贡献者可以点击预览链接查看修改后的文档效果，确认修改是否符合预期。维护团队会对 PR 进行评审，如有修改建议会在 PR 中留言，贡献者根据反馈进行修改。评审通过后，维护团队会 merge PR，文档贡献即完成。 + +== **组件贡献** + +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，添加 `extension` 标签，并分配给自己。新建 Issue 的格式可参考已有的生态组件适配类 Issue：标题格式为 `Ecosystem Integration: <组件名>`，正文用一句话说明要适配的组件及其用途。 + +维护者会评估该组件是否适合纳入 IvorySQL 生态，并在 Issue 中与您沟通确认。 + +[TIP] +建议在 Issue 获得维护者确认后再开始适配工作，避免重复或无效工作。 + +===== 签署 CLA + +在提交文档贡献之前，请确保您已签署贡献者许可协议（CLA）。详情请参阅本指南的签署 CLA。 + +==== 适配测试 + +生态组件适配的目标分为两个层面： + +- 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 + +按照 xref:#_提交_pr[提交 PR] 章节的步骤创建 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/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/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.