# Contributing to BK-CI

蓝鲸团队秉持开放的态度，欢迎志同道合的开发者一起贡献项目。在开始之前，请认真阅读以下指引。

## 代码协议

[MIT LICENSE](LICENSE.txt) 为 BK-CI 的开源协议，任何人贡献的代码也会受此协议保护，贡献代码前也请明确是否可以接受该协议。

## 设计文档

任何功能和特性都应该要有相应的设计文档。设计文档需要归档到**docs/fetures**目录中，方便团队进行审阅，也方便后续加入的开发者了解特性设计
详情。

## 贡献功能与特性

如果想对BK-CI项目贡献功能与特性，请参考以下步骤：

* 联系蓝鲸团队反馈相关的功能需求；
* 一旦团队认同该功能，则创建需要issue追溯该特性。 issue应该至少包含特性需要解决的问题、用例、相关设计、实现细节以及可能遇到的问题
* 提交详细的设计文档给蓝鲸团队
* 蓝鲸团队确认需求排期，确认功能与特性合并时间与版本
* 完成编码，单元测试，测试用例，以及特性使用文档，确认一致的代码风格
* 提交Pull Request/Merge Request，包含文档与代码
* 功能/特性review，通过后合并

> 注意：为了保证代码质量，对于大的特性与功能，蓝鲸团队更倾向渐进式，积木式的多次PRs/MRs提交，如此方便相关开发者review其中变化的细节。一次性、大规模的提交可能会花费更多的时间进行review

## 如何开始

想要贡献代码，建议请先参照已有的特性文档和开发环境构建文档。

## GIT提交规范

因不同团队不同的项目管理下会有不同的代码提交注释，规范化开源下对不同团队提交信息，做了不同的提交标记以规范化区分提交内容：

```
git commit -m '标记: 提交的概要注释 issue #123'
```

示例:

```shell
git commit -m 'fix: 部分第三方构建机上出现worker-agent.jar进程延迟退出的问题 #29'
```

### 标记说明:

| 标记     | 说明                                   |
| -------- | -------------------------------------- |
| feature/feat  | 新功能开发                             |
| bug/fix/bugfix   | bug修复                                |
| refactor/perf | 重构代码/优化配置&参数/优化逻辑及功能 |
| test     | 添加单元测试用例相关                   |
| docs     | 添加文档                               |
| info     | 添加注释类信息                         |
| format   | 不修改业务逻辑下，仅做代码规范的格式化 |
| merge    | 仅做分支合并同步                       |
| depend   | 对工程的依赖进行增删改                 |
| chore    | 构建脚本、任务等相关代码                 |
| del    | 删除可能仍然有人用到的功能、API等破坏性动作               |


## Pull Request/Merge Request

如果你已经在处理现有的issue，对此已经有合理的解决方案，建议你在当前issue上进行回复，让蓝鲸团队或者其他开发者、使用者了解到你对该问题有兴趣，并取得了积极的进展，防止重复开发建设，避免人力浪费。蓝鲸团队抱着开放的态度，非常乐意与大家磋商解决方案，期待大家提交PR/MR。

提交建议修复的步骤：

* fork受到该issue影响的分支
* 创建你自己的修复分支
* 修复问题
* 新增测试用例，如果是bug fix，确保在没有修复代码的情况下，测试用例应该无法通过；测试用例请尽可能覆盖各种情况
* 更新文档（如需要）
* 编译成功，并通过单元测试
* review，通过后合并

对于issue的修复，蓝鲸团队希望一个PR/MR能涵盖所有相关的内容，包括但不限于代码，修复文档与使用说明。

相关的review流程请参照：[BK-CI review相关流程](./docs/specification/review.md)

## Issues

蓝鲸团队使用[issues](https://github.com/Tencent/bk-ci/issues)进行bugs追踪、特性追踪等。

当提交相关的bug时，请查找已存在或者相类似的issue，从而保证不存在冗余。

如果确认该bug是一个新的bug，提交时请包含以下的信息：

* 你所使用的操作系统信息
* 当前你使用的版本信息，例如version，commitid
* 出现问题时，相关模块的日志输出
* 重现该问题的准确步骤，例如提交相关重现脚本/工具会比大量描述更有用一些