如何参与和贡献ShardingSphere（上）-京东云开发者社区

ShardingSphere是一个开放且活跃的社区，非常欢迎高质量的参与者与我们共建开源之路。

您可以从订阅官方邮件列表开始参与社区。

在成为一个贡献者之前，请您阅读贡献者指南、官方文档指南以及开发规范。

如果你想成为官方提交者，请您阅读提交者指南。官方提交者需要通过开启2FA后，才能够行使Apache官方代码仓库权限。

如果你想成为官方版本发布经理，请您阅读发布指南。

感谢您关注ShardingSphere。
# 订阅指南
在使用ShardingSphere的过程中，如果您发现任何问题，有新的想法、建议都可以通过Apache邮件列表参与到ShardingSphere的社区建设中。

1. 发送订阅邮件。
用自己的邮箱向[dev-subscribe@shardingsphere.apache.org](mailto:dev-subscribe@shardingsphere.apache.org)发送一封邮件，主题和内容任意。

1. 接收确认邮件并回复。
完成步骤1后，您将收到一封来自[dev-help@shardingsphere.apache.org](mailto:dev-help@shardingsphere.apache.org)的确认邮件（如未收到，请确认该邮件是否已被拦截，或已经被自动归入订阅邮件、垃圾邮件、推广邮件等文件夹）。直接回复该邮件，或点击邮件里的链接快捷回复即可，主题和内容任意。
 
1. 接收欢迎邮件。
完成以上步骤后，您会收到一封主题为`WELCOME to dev@shardingsphere.apache.org`的欢迎邮件，至此您已成功订阅Apache ShardingSphere的邮件列表。

1. 至此，您可以通过订阅的邮箱接收及回复邮件，或通过查看[归档邮件](https://lists.apache.org/list.html?dev@shardingsphere.apache.org)来跟踪邮件对话。

# 贡献者指南

您可以报告bug，提交一个新的功能增强建议或者直接对以上内容提交改进补丁。

## 提交issue

- 在提交issue之前，请经过充分的搜索，确定该issue不是通过简单的检索即可以解决的问题。
 - 查看[issue列表](https://github.com/apache/shardingsphere/issues)，确定该issue不是一个重复的问题。
 - [新建](https://github.com/apache/shardingsphere/issues/new/choose)一个issue并选择您的issue类型。
 - 使用一个清晰并有描述性的标题来定义issue。
 - 根据模板填写必要信息。
 - 在提交issue之后，对该issue分配合适的标签。如：bug，enhancement，discussion等。
 - 请对自己提交的issue保持关注，在讨论中进一步提供必要信息。

## 开发流程

**1. Fork分支到本地，设置upstream**

- 从shardingsphere的repo上fork一个分支到您自己的repo来开始工作，并设置upstream为shardingsphere的repo。

```shell
git remote add upstream https://github.com/apache/shardingsphere.git
```

**2. 选择issue**

- 请在选择您要修改的issue。如果是您新发现的问题或想提供issue中没有的功能增强，请先新建一个issue并设置正确的标签。
 - 在选中相关的issue之后，请回复以表明您当前正在这个issue上工作。并在回复的时候为自己设置一个deadline，添加至回复内容中。
 - 在[开发者列表](/cn/contribute/contributor/)中找到一个导师，导师会在设计与功能实现上给予即时的反馈。

**3. 创建分支**

- 切换到fork的master分支，拉取最新代码，创建本次的分支。

```shell
git checkout master
git pull upstream master
git checkout -b issueNo
```

**注意** ：PR会按照squash的方式进行merge，如果不创建新分支，本地和远程的提交记录将不能保持同步。

**4. 编码**

- 请您在开发过程中遵循ShardingSphere的[开发规范](/cn/contribute/code-conduct/)。并在准备提交pull request之前完成相应的检查。
 - 将修改的代码push到fork库的分支上。

```shell
git add 修改代码
git commit -m 'commit log'
git push origin issueNo
```

**5. 提交PR**

- 发送一个pull request到ShardingSphere的master分支。
 - 接着导师做CodeReview，然后他会与您讨论一些细节（包括设计，实现，性能等）。当导师对本次修改满意后，会将提交合并到当前开发版本的分支中。
 - 最后，恭喜您已经成为了ShardingSphere的官方贡献者！

**6. 删除分支**

- 在导师将pull request合并到ShardingSphere的master分支中之后，您就可以将远程的分支（origin/issueNo）及与远程分支（origin/issueNo）关联的本地分支（issueNo）删除。
 
```shell
git checkout master
git branch -d issueNo
git push origin --delete issueNo
```

**注意**: 为了让您的id显示在contributor列表中，别忘了以下设置：

```shell
git config --global user.name "username"
git config --global user.email "username@mail.com"
```
# 提交者指南
## 提交者提名

ShardingSphere社区遵循[Apache Community’s process](http://community.apache.org/newcommitter.html) 来接收新的提交者。
当您积极地参与ShardingSphere社区之后，项目管理委员会和项目官方提交者会根据您的表现发起吸纳您成为官方提交者和项目管理委员会成员的流程。

## 提交者责任

- 开发新功能；
 - 代码重构；
 - 及时和可靠的评审Pull Request；
 - 思考和接纳新特性请求；
 - 解答问题；
 - 维护文档和代码示例；
 - 改进流程和工具；
 - 引导新的参与者融入社区。

## 日常工作

1. 每周负责轮值的Committer需要每天查看社区待处理的Pull Request和Issue列表，负责问题的处理：

- 包括标记issue，回复issue，关闭issue等；
 - 将issue分配至熟悉该模块的贡献者；
 - 轮值周期为一周。

2. Assignee在被分配issue后，需要进行如下判断：

- 判断是否是长期issue，如是，则标记为pending；
 - 判断issue类型，如：bug，enhancement，discussion等；
 - 标记Milestone。

3. Committer提交的PR，需要根据PR类型和当前发布的周期标注Label和Milestone。

4. Committer review PR时，可以进行squash and merge to master的操作, 如果有问题可以加上change request或者@相关人员协助处理。
# 开发规范
以下行为准则以完全遵循[Apache软件基金会行为准则](https://www.apache.org/foundation/policies/conduct.html)为前提。

## 开发理念

- **用心** 保持责任心和敬畏心，以工匠精神持续雕琢。
 - **可读** 代码无歧义，通过阅读而非调试手段浮现代码意图。
 - **整洁** 认同《重构》和《代码整洁之道》的理念，追求整洁优雅代码。
 - **一致** 代码风格、命名以及使用方式保持完全一致。
 - **精简** 极简代码，以最少的代码表达最正确的意思。高度复用，无重复代码和配置。及时删除无用代码。
 - **抽象** 层次划分清晰，概念提炼合理。保持方法、类、包以及模块处于同一抽象层级。
 - **极致** 拒绝随意，保证任何一行代码、任何一个字母、任何一个空格都有其存在价值。

## 代码提交行为规范

- 确保通过全部测试用例，确保执行`./mvnw clean install`可以编译和测试通过。
 - 确保覆盖率不低于master分支。
 - 确保使用Checkstyle检查代码，违反验证规则的需要有特殊理由。模板位置在`https://github.com/apache/shardingsphere/blob/master/src/resources/checkstyle.xml`，请使用checkstyle 8.8运行规则。
 - 应尽量将设计精细化拆分；做到小幅度修改，多次数提交，但应保证提交的完整性。
 - 确保遵守编码规范。
 - 如果您使用IDEA，可导入推荐的[Settings](https://shardingsphere.apache.org/community/data/shardingsphere-settings.jar)。
 
## 编码规范

- 使用linux换行符。
 - 缩进（包含空行）和上一行保持一致。
 - 类声明后与下面的变量或方法之间需要空一行。
 - 不应有无意义的空行。请提炼私有方法，代替方法体过长或代码段逻辑闭环而采用的空行间隔。
 - 类、方法和变量的命名要做到顾名思义，避免使用缩写。
 - 返回值变量使用`result`命名；循环中使用`each`命名循环变量；map中使用`entry`代替`each`。
 - 捕获的异常名称命名为`ex`；捕获异常且不做任何事情，异常名称命名为`ignored`。
 - 配置文件使用`Spinal Case`命名（一种使用`-`分割单词的特殊`Snake Case`）。
 - 需要注释解释的代码尽量提成小方法，用方法名称解释。
 - `equals`和`==`条件表达式中，常量在左，变量在右；大于小于等条件表达式中，变量在左，常量在右。
 - 除了构造器入参与全局变量名称相同的赋值语句外，避免使用`this`修饰符。
 - 除了用于继承的抽象类之外，尽量将类设计为`final`。
 - 嵌套循环尽量提成方法。
 - 成员变量定义顺序以及参数传递顺序在各个类和方法中保持一致。
 - 优先使用卫语句。
 - 类和方法的访问权限控制为最小。
 - 方法所用到的私有方法应紧跟该方法，如果有多个私有方法，书写私有方法应与私有方法在原方法的出现顺序相同。
 - 方法入参和返回值不允许为`null`。
 - 优先使用三目运算符代替if else的返回和赋值语句。
 - 优先使用lombok代替构造器，getter, setter方法和log变量。
 - 优先考虑使用`LinkedList`，只有在需要通过下标获取集合中元素值时再使用`ArrayList`。
 - `ArrayList`，`HashMap`等可能产生扩容的集合类型必须指定集合初始大小，避免扩容。
 - 日志与注释一律使用英文。
 - 注释只能包含javadoc，todo和fixme。
 - 公开的类和方法必须有javadoc，其他类和方法以及覆盖自父类的方法无需javadoc。

## 单元测试规范

- 测试代码和生产代码需遵守相同代码规范。
 - 单元测试需遵循AIR（Automatic, Independent, Repeatable）设计理念。
   - 自动化（Automatic）：单元测试应全自动执行，而非交互式。禁止人工检查输出结果，不允许使用`System.out`，`log`等，必须使用断言进行验证。
   - 独立性（Independent）：禁止单元测试用例间的互相调用，禁止依赖执行的先后次序。每个单元测试均可独立运行。
   - 可重复执行（Repeatable）：单元测试不能受到外界环境的影响，可以重复执行。
 - 单元测试需遵循BCDE（Border, Correct, Design, Error）设计原则。
   - 边界值测试（Border）：通过循环边界、特殊数值、数据顺序等边界的输入，得到预期结果。
   - 正确性测试（Correct）：通过正确的输入，得到预期结果。
   - 合理性设计（Design）：与生产代码设计相结合，设计高质量的单元测试。
   - 容错性测试（Error）：通过非法数据、异常流程等错误的输入，得到预期结果。
 - 如无特殊理由，测试需全覆盖。
 - 每个测试用例需精确断言。
 - 准备环境的代码和测试代码分离。
 - 只有junit `Assert`，hamcrest `CoreMatchers`，Mockito相关可以使用static import。
 - 单数据断言，应使用`assertTrue`，`assertFalse`，`assertNull`和`assertNotNull`。
 - 多数据断言，应使用`assertThat`。
 - 精确断言，尽量不使用`not`，`containsString`断言。
 - 测试用例的真实值应名为为actualXXX，期望值应命名为expectedXXX。
 - 测试类和`@Test`标注的方法无需javadoc。

## G4编码规范
 - 公共规范
   - 每行长度不超过`200`个字符，保证每一行语义完整以便于理解。
 - 词法解析规范
   - 每个规则一行，规则间无需空行。
   - 规则名称使用大写字母。如果名称由多个单词组成，用`下划线`间隔。`DataType`和`Symbol`的规则命名以`下划线`结尾。与ANTLR内置变量或关键字重名的规则在结尾加`下划线`以示区分。
   - 不对外暴露的规则使用`fragment`，`fragment`定义的规则需在其服务的规则之后声明。
   - 公用规则定义放在`Keyword.g4`，每个数据库可以有自己特有的规则定义。例如：`MySQLKeyword.g4`。
 - 语法解析规范
   - 每个规则结束后空一行，空行无需缩进。
   - 规则名称前面不空格，`冒号`后空一格再开始写规则，`分号`在单独一行并保持和上一行相同缩进。
   - 如果一个规则的分支超过`5`个，则每个分支一行。
   - 规则命名采用java变量的驼峰形式。
   - 为每种SQL语句类型定义一个独立的语法文件，文件名称由`数据库名称` + `语句类型名称` + `Statement`。例如：`MySQLDQLStatement.g4`。
   
# Issue 提交与处理规范

## Issue 提交规范

- Issue 列表以可读和可检索为目标。提交者有义务将标题总结的有意义和易于检索，并保持内容的正确和完整性；
 - 请在经过充分的检索之后，确定无相关的已存在 Issue，再提交新的 Issue；
 - Issue 类型划分为缺陷报告、新功能请求和问题，请在提交 Issue 时选择正确的模板并根据模板填写其内容；
 - 由配置不确定等产生的问题，请将相关的可重现代码提交至 Github，以便于社区贡献者定位和确定问题；
 - 请在 Issue 得到解决之后，回复该 Issue，形成闭环，为其他浏览此 Issue 的读者提供有效信息；
 - 请及时关注已提交的 Issue，长时间无反馈的 Issue 将定期关闭；
 - 为保证社区多元化，请使用英文参与交流。

## Issue 处理规范

- 对于标题不明晰的 Issue，由处理人引导提交者将标题修改完善后再行处理；
 - 对于内容缺失模板必要信息的 Issue，由处理人引导提交者将所需信息提供完善后再行处理；
 - 涉及到缺陷修复、功能提升等与代码相关的 Issue，都将标记正确的标签以及完成此 Issue 的项目版本；
 - 处理人将定期关闭长时间无反馈的 Issue；
 - 无参考和检索价值的 Issue 将被标记为 Invalid，读者无需关注。