Skip to content

update contribution guide and add README_zh #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 28, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified CN/modules/ROOT/images/14.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion CN/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
83 changes: 83 additions & 0 deletions CN/modules/ROOT/pages/v4.4/32.adoc
Original file line number Diff line number Diff line change
@@ -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: <https://github.com/IvorySQL>。

请参考<https://docs.github.com/en/get-started/start-your-journey>注册您的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 社区贡献,我们的目标是发展一个由贡献者组成的活跃、健康的社区。
88 changes: 88 additions & 0 deletions CN/modules/ROOT/pages/v4.4/33.adoc
Original file line number Diff line number Diff line change
@@ -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 按钮, 提交即可。

提交问题以后,如果问题的描述和复现步骤清晰明确和可定位,会有人直接定位和解决该问题。但也有可能会出现,负责跟进该问题的开发者需要您提供更加详细的信息的情况,也感谢您的配合。
Binary file modified EN/modules/ROOT/images/14.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
107 changes: 107 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
@@ -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链接,点击链接即可实现预览。
Loading
Loading