diff --git a/CN/modules/ROOT/images/14.png b/CN/modules/ROOT/images/14.png index 0c83291..478a600 100755 Binary files a/CN/modules/ROOT/images/14.png and b/CN/modules/ROOT/images/14.png differ diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 03cc2dc..6f41aca 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -33,6 +33,6 @@ ** xref:v4.4/27.adoc[11、兼容Oracle sequence] ** xref:v4.4/28.adoc[12、包] ** xref:v4.4/29.adoc[13、不可见列] -* xref:v4.4/23.adoc[社区贡献指南] +* xref:v4.4/32.adoc[社区贡献指南] * xref:v4.4/24.adoc[工具参考] * xref:v4.4/25.adoc[FAQ] \ No newline at end of file diff --git a/CN/modules/ROOT/pages/v4.4/32.adoc b/CN/modules/ROOT/pages/v4.4/32.adoc new file mode 100644 index 0000000..406bfd5 --- /dev/null +++ b/CN/modules/ROOT/pages/v4.4/32.adoc @@ -0,0 +1,83 @@ + +:sectnums: +:sectnumlevels: 5 + +:imagesdir: ./_images += **IvorySQL社区贡献指南** + +IvorySQL由一个核心开发团队维护,该团队拥有对GitHub上的IvorySQL主存储库的提交权限。同时,我们非常渴望从更广泛的IvorySQL社区中的成员那里获得贡献。如果您希望看到您的代码或文档更改被添加到IvorySQL并出现在将来的版本中,本节的内容介绍是您需要知道的。 + +​IvorySQL社区欢迎并赞赏所有类型的贡献,期待您的加入! + +在参与社区贡献前,请先阅读并遵守 https://github.com/IvorySQL/IvorySQL/blob/master/CODE_OF_CONDUCT_CN.md[IvorySQL社区行为准则]。 + +== 注册Github账号 + +IvorySQL源码托管在github: 。 + +请参考注册您的github账号,并熟悉Git工具和工作流。 + +== 签署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 +如果您准备向社区上报 Bug 或者提交需求,请在 IvorySQL 社区对应的仓库上提交 Issue,并参考Issue xref:./33.adoc[提交指南]。 + +=== 给自己分配Issue +您可以将自己创建的Issue或者愿意处理的Issue分配给自己。 只需要在评论框内输入/assign,机器人就会将问题分配给您。 每个 Issue 下面可能已经有参与者的交流和讨论,如果您感兴趣,也可以在评论框中发表自己的意见参与 Issue 讨论。 + +=== 提交Pull Request +对于提交一个PR应该保持一个功能,或者一个bug提交一次。禁止多个功能一次提交。 + + +==== 第1步:创建一个Pull Request + +1、打开你 Fork 的仓库: https://github.com/$user/$repo_addr (将 $user 替换为你的 GitHub ID)。 + +​2、点击 Compare & pull request 按钮 + +==== 第2步:填写PR信息 + +``` +Fix test +功能描述 +``` + +``` +leave a comment +对该提交功能进行比较详细的描述 +``` + +==== 第3步:提交PR + +点击Create pull request 按钮即可提交。 + + +== 致谢 +我们欢迎所有人参与 IvorySQL 社区贡献,我们的目标是发展一个由贡献者组成的活跃、健康的社区。 diff --git a/CN/modules/ROOT/pages/v4.4/33.adoc b/CN/modules/ROOT/pages/v4.4/33.adoc new file mode 100644 index 0000000..97fb7e0 --- /dev/null +++ b/CN/modules/ROOT/pages/v4.4/33.adoc @@ -0,0 +1,88 @@ + +:sectnums: +:sectnumlevels: 5 + +:imagesdir: ./_images += **问题提交指南** +发现并提交问题,也是对社区良好的贡献方式。 + +本文详细描述如何提交一个问题。 + +以IvorySQL为例,提交一个bug report + +== 确认问题所属仓库 +IvorySQL仓库: https://github.com/IvorySQL/IvorySQL + +== **创建新的Issue** + +=== 第1步 进入New issue 页面: + +点击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 按钮, 提交即可。 + +提交问题以后,如果问题的描述和复现步骤清晰明确和可定位,会有人直接定位和解决该问题。但也有可能会出现,负责跟进该问题的开发者需要您提供更加详细的信息的情况,也感谢您的配合。 diff --git a/EN/modules/ROOT/images/14.png b/EN/modules/ROOT/images/14.png index 0c83291..478a600 100755 Binary files a/EN/modules/ROOT/images/14.png and b/EN/modules/ROOT/images/14.png differ diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..c2015d2 --- /dev/null +++ b/README_zh.md @@ -0,0 +1,107 @@ +# Ivorysql_docs + +简体中文 | [English](./README.md) + +## 介绍 + +欢迎来到IvorySQL社区文档的仓库。此仓库提供[IvorySQL文档中心](https://docs.ivorysql.org/cn/index.html)呈现的所有文档,包括发行说明、IvorySQL入门、IvorySQL高级、IvorySQL生态、IvorySQL架构设计、Oracle兼容功能列表、社区贡献指南、工具参考、FAQ等内容。 +## 贡献 + +我们非常欢迎您贡献文档!如果想要参与,请阅读[贡献范围](#贡献范围)、遵守文档写作[规范说明](#规范说明)、按照流程规则提交。审核通过后,修改会在社区的文档中心中呈现。 + +同时,如果您对文档有任何意见或建议,请在Issue中提交。 + +## 准备工作 + +(1)下载Asciidoc或者Typora文档编辑器。 + +(2)检查源仓库是否有更新,如果有更新请先更新并同步到自己的仓库。如有更新请参阅以下步骤,更新至最新版本: + +``` +git remote + +git fetch upstream + +git merge upstream/main + +git push +``` + +(3)熟悉[文档写作规范](#规范说明) + +## 贡献范围 + +IvorySQL社区提供双语文档。英文文档保存在EN/中,中文文档保存在CN/中。您可以为任何一方文档做出贡献,当然您也可以为两方同时做出贡献。 + +​ 您可以从以下任何一项开始,以帮助改进[IvorySQL文档中心](https://docs.ivorysql.org)上的文档: + +​ (1) 编写完善文档 + +​ (2) 修复拼写错误或格式(标点符号、空格、缩进、代码块等) + +​ (3) 修正或更新不当或过时的说明 + +​ (4) 添加缺少的内容(句子、段落或新文档) + +​ (5) 将文档更改从英文翻译成中文,或从中文翻译成英文。 + +​ (6) 提交、回复和解决文档问题 + +​ (7) (高级)查看其他人创建的拉取请求 + +## 规范说明 + +IvorySQL文档是用“asciidoc”编写,具体请参考[adoc规范](./adoc_syntax_quick_reference.md)。 + +## 本地网页生成 +通过之前的内容,您就可以进行文档贡献,最终push到您个人的ivorysql_docs仓库中。 + +另外,您可能需要知道网页对应的ui的位置,如下图: + +![image](CN/modules/ROOT/images/15.png) + +中英文的网页ui模板基本一致,因此修改时应该尽量保证同时修改两个模板。 + +如果您文档贡献修改的内容较多,建议在提交PR前,先在本地进行预览,具体步骤如下: + +### 环境准备 + +安装Node.js +``` +sudo yum install -y nodejs +sudo npm install -g serve@14.2.4 +``` +安装Antora +``` +npm install antora@3.1.7 +npm install @antora/pdf-extension +npm install @antora/lunr-extension +npm install nodejieba +npm install @asciidoctor/core asciidoctor-pdf +npx antora -v +alias antora='npx antora' #将npx antora更名为antora +antora -v +``` +最终,在终端上显示如下即为成功安装。 + +![image](CN/modules/ROOT/images/14.png) + + +### 编译步骤 + +文档中心是由 `Antora` 进行搭建的,doc-builder仓库负责编译: +* `fork` [doc-builder仓库](https://github.com/IvorySQL/ivory-doc-builder) +* `clone` doc-builder仓库到本地 + + `git clone https://github.com/yourname/ivory-doc-builder.git` +* doc-builder 编译 + + `antora generate --to-dir ../demo antora-playbook-CN.yml --stacktrace` + + 然后耐心等待,当成功运行结束后,你就可以到../demo 中查看自己生成的网页了。 + +检查之后,你就可以开始提交[PR](https://github.com/IvorySQL/ivorysql_docs/blob/v4.4/CN/modules/ROOT/pages/v4.4/32.adoc),感谢您对社区的贡献^ _ ^,我们会在审核过后,考虑是否更新网站。 + +## Autobuild + +在Ivorysql-docs的仓库中提交的每一个PR, PR会话中会分别产生中文/英文的Deploy Preview链接,点击链接即可实现预览。 diff --git a/adoc_syntax_quick_reference.md b/adoc_syntax_quick_reference.md new file mode 100644 index 0000000..24de506 --- /dev/null +++ b/adoc_syntax_quick_reference.md @@ -0,0 +1,471 @@ +# asciidoc语法快速参考 +IvorySQL文档是用“asciidoc”编写的。为确保格式的质量和一致性,在修改更新文档时应遵循某些 [asciidoc](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) 规则。 + + +## 规范说明 + + + +​ **asciidoc规范** + +​ 1、标题从一级开始递增使用,禁止跳级使用。例如:一级标题下面不能直接使用三级标题;二级标题下面不能直接使用四级标题。 + +​ 2、标题必须统一使用 ATX 风格,即在标题前加 = 号来表示标题级别。 + +​ 3、标题的引导符号 = 后必须空一格再接标题内容。 + +​ 4、标题的引导符号“=”后只能空一格后再接标题内容,不能有多个空格。 + +​ 5、标题必须出现在一行行首,即标题的 = 号前不能有任何空格。 + +​ 6、标题末尾仅能出现中英文问号、反引号、中英文单双引号等符号。其余如冒号、逗号、句号、感叹号等符号均不能在标题末尾使用。 + +​ 7、标题上面须空一行。 + +​ 8、文档中不能连续出现内容重复的标题,如一级标题为 = IvorySQL 架构,紧接着的二级标题就不能是 == IvorySQL 架构。如果不是连续的标题,则标题内容可重复。 + +​ 9、文档中只能出现一个一级标题。 + +​ 10、一般来说,除 TOC.adoc 文件可缩进 2 个空格外,其余所有 .adoc 文件每缩进一级,默认须缩进 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.adoc 文件可缩进 2 个空格外,其余所有 .adoc 文件每缩进一级,默认须缩进 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. +```