diff --git a/docs/contribute_guide/assets/分支管理.drawio b/docs/contribute_guide/assets/分支管理.drawio new file mode 100644 index 00000000..0e7e3d37 --- /dev/null +++ b/docs/contribute_guide/assets/分支管理.drawio @@ -0,0 +1,111 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/contribute_guide/assets/分支管理.png b/docs/contribute_guide/assets/分支管理.png new file mode 100644 index 00000000..867fecd4 Binary files /dev/null and b/docs/contribute_guide/assets/分支管理.png differ diff --git a/docs/contribute_guide/assets/环境初始化.jpg b/docs/contribute_guide/assets/环境初始化.jpg new file mode 100644 index 00000000..31ff5f28 Binary files /dev/null and b/docs/contribute_guide/assets/环境初始化.jpg differ diff --git a/docs/contribute_guide/assets/申请合并.jpg b/docs/contribute_guide/assets/申请合并.jpg new file mode 100644 index 00000000..d02a7f50 Binary files /dev/null and b/docs/contribute_guide/assets/申请合并.jpg differ diff --git a/docs/contribute_guide/assets/问题认领.jpg b/docs/contribute_guide/assets/问题认领.jpg new file mode 100644 index 00000000..62da4728 Binary files /dev/null and b/docs/contribute_guide/assets/问题认领.jpg differ diff --git a/docs/contributer_guide/代码规范.md b/docs/contribute_guide/代码规范.md similarity index 100% rename from docs/contributer_guide/代码规范.md rename to docs/contribute_guide/代码规范.md diff --git a/docs/contribute_guide/贡献指南.md b/docs/contribute_guide/贡献指南.md new file mode 100644 index 00000000..37cf89bc --- /dev/null +++ b/docs/contribute_guide/贡献指南.md @@ -0,0 +1,167 @@ +# 贡献指南 + +- [贡献指南](#贡献指南) + - [1、行为准则](#1行为准则) + - [2、仓库规范](#2仓库规范) + - [2.1、Issue 规范](#21issue-规范) + - [2.2、Commit-Log 规范](#22commit-log-规范) + - [2.3、Pull-Request 规范](#23pull-request-规范) + - [3、操作示例](#3操作示例) + - [3.1、初始化环境](#31初始化环境) + - [3.2、认领问题](#32认领问题) + - [3.3、处理问题 \& 提交解决](#33处理问题--提交解决) + - [3.4、请求合并](#34请求合并) + - [4、常见问题](#4常见问题) + - [4.1、如何将多个 Commit-Log 合并为一个?](#41如何将多个-commit-log-合并为一个) + + +--- + + +欢迎 👏🏻 👏🏻 👏🏻 来到 `KnowStreaming`。本文档是关于如何为 `KnowStreaming` 做出贡献的指南。如果您发现不正确或遗漏的内容, 请留下您的意见/建议。 + + +--- + + +## 1、行为准则 + +请务必阅读并遵守我们的:[行为准则](https://github.com/didi/KnowStreaming/blob/master/CODE_OF_CONDUCT.md)。 + + +## 2、仓库规范 + +### 2.1、Issue 规范 + +按要求,在 [创建Issue](https://github.com/didi/KnowStreaming/issues/new/choose) 中创建ISSUE即可。 + +需要重点说明的是: +- 提供出现问题的环境信息,包括使用的系统,使用的KS版本等; +- 提供出现问题的复现方式; + + +### 2.2、Commit-Log 规范 + +`Commit-Log` 包含三部分 `Header`、`Body`、`Footer`。其中 `Header` 是必须的,格式固定,`Body` 在变更有必要详细解释时使用。 + + +**1、`Header` 规范** + +`Header` 格式为 `[Type]Message(#IssueID)`, 主要有三部分组成,分别是`Type`、`Message`、`IssueID`, + +- `Type`:说明这个提交是哪一个类型的,比如有 Bugfix、Feature、Optimize等; +- `Message`:说明提交的信息,比如修复xx问题; +- `IssueID`:该提交,关联的Issue的编号; + + +实际例子:[`[Bugfix]修复新接入的集群,Controller-Host不显示的问题(#927)`](https://github.com/didi/KnowStreaming/pull/933/commits) + + + +**2、`Body` 规范** + +一般不需要,如果解决了较复杂问题,或者代码较多,需要 `Body` 说清楚解决的问题,解决的思路等信息。 + +--- + +**3、实际例子** + +``` +[Optimize]优化 MySQL & ES 测试容器的初始化(#906) + +主要的变更 +1、knowstreaming/knowstreaming-manager 容器; +2、knowstreaming/knowstreaming-mysql 容器调整为使用 mysql:5.7 容器; +3、初始化 mysql:5.7 容器后,增加初始化 MySQL 表及数据的动作; + +被影响的变更: +1、移动 km-dist/init/sql 下的MySQL初始化脚本至 km-persistence/src/main/resource/sql 下,以便项目测试时加载到所需的初始化 SQL; +2、删除无用的 km-dist/init/template 目录; +3、因为 km-dist/init/sql 和 km-dist/init/template 目录的调整,因此也调整 ReleaseKnowStreaming.xml 内的文件内容; +``` + + +**TODO : 后续有兴趣的同学,可以考虑引入 Git 的 Hook 进行更好的 Commit-Log 的管理。** + + +### 2.3、Pull-Request 规范 + +详细见:[PULL-REQUEST 模版](../../.github/PULL_REQUEST_TEMPLATE.md) + +需要重点说明的是: + +- 任何 PR 都必须与有效 ISSUE 相关联。否则, PR 将被拒绝; +- 一个分支只修改一件事,一个 PR 只修改一件事; + +--- + + +## 3、操作示例 + +本节主要介绍对 `KnowStreaming` 进行代码贡献时,相关的操作方式及操作命令。 + +名词说明: +- 主仓库:https://github.com/didi/KnowStreaming 这个仓库为主仓库。 +- 分仓库:Fork 到自己账号下的 KnowStreaming 仓库为分仓库; + + +### 3.1、初始化环境 + +1. `Fork KnowStreaming` 主仓库至自己账号下,见 https://github.com/didi/KnowStreaming 地址右上角的 `Fork` 按钮; +2. 克隆分仓库至本地:`git clone git@github.com:xxxxxxx/KnowStreaming.git`,该仓库的简写名通常是`origin`; +3. 添加主仓库至本地:`git remote add upstream https://github.com/didi/KnowStreaming`,`upstream`是主仓库在本地的简写名,可以随意命名,前后保持一致即可; +4. 拉取主仓库代码:`git fetch upstream`; +5. 拉取分仓库代码:`git fetch origin`; +6. 将主仓库的`master`分支,拉取到本地并命名为`github_master`:`git checkout -b upstream/master`; + +最后,我们来看一下初始化完成之后的大致效果,具体如下图所示: +![环境初始化](./assets/环境初始化.jpg) + + +至此,我们的环境就初始化好了。后续,`github_master` 分支就是主仓库的`master`分支,我们可以使用`git pull`拉取该分支的最新代码,还可以使用`git checkout -b xxx`拉取我们想要的分支。 + + + +### 3.2、认领问题 + +在文末评论说明自己要处理该问题即可,具体如下图所示: + +![问题认领](./assets/问题认领.jpg) + + +### 3.3、处理问题 & 提交解决 + +本节主要介绍一下处理问题 & 提交解决过程中的分支管理,具体如下图所示: + +![分支管理](./assets/分支管理.png) + +1. 切换到主分支:`git checkout github_master`; +2. 主分支拉最新代码:`git pull`; +3. 基于主分支拉新分支:`git checkout -b fix_928`; +4. 提交代码,安装commit的规范进行提交,例如:`git commit -m "[Optimize]优化xxx问题(#928)"`; +5. 提交到自己远端仓库:`git push --set-upstream origin fix_928`; +6. `GitHub` 页面发起 `Pull Request` 请求,管理员合入主仓库。这部分详细见下一节; + + +### 3.4、请求合并 + +代码在提交到 `GitHub` 分仓库之后,就可以在 `GitHub` 的网站创建 `Pull Request`,申请将代码合入主仓库了。 `Pull Request` 具体见下图所示: + +![申请合并](./assets/申请合并.jpg) + + + +[Pull Request 创建的例子](https://github.com/didi/KnowStreaming/pull/945) + + + +--- + + +## 4、常见问题 + +### 4.1、如何将多个 Commit-Log 合并为一个? + +可以使用 `git rebase -i` 命令进行解决。 + + diff --git a/docs/contribute_guide/贡献记录.md b/docs/contribute_guide/贡献记录.md new file mode 100644 index 00000000..f2e31a13 --- /dev/null +++ b/docs/contribute_guide/贡献记录.md @@ -0,0 +1,82 @@ +## 10.6 贡献者名单 + +#### KnowStreaming 开发者角色 + +KnowStreaming 开发者包含 Maintainer、Committer、Contributor 三种角色,每种角色的标准定义如下。 + +##### Maintainer + +Maintainer 是对 KnowStreaming 项目的演进和发展做出显著贡献的个人。具体包含以下的标准: + +- 完成多个关键模块或者工程的设计与开发,是项目的核心开发人员; +- 持续的投入和激情,能够积极参与社区、官网、issue、PR 等项目相关事项的维护; +- 在社区中具有有目共睹的影响力,能够代表 KnowStreaming 参加重要的社区会议和活动; +- 具有培养 Committer 和 Contributor 的意识和能力; + +##### Committer + +Committer 是具有 KnowStreaming 仓库写权限的个人,包含以下的标准: + +- 能够在长时间内做持续贡献 issue、PR 的个人; +- 参与 issue 列表的维护及重要 feature 的讨论; +- 参与 code review; + +##### Contributor + +Contributor 是对 KnowStreaming 项目有贡献的个人,标准为: + +- 提交过 PR 并被合并; + +开源贡献者名单(定期更新) + +在名单内,但是没有收到贡献者礼品的同学,可以联系:szzdzhp001 + +| 姓名 | Github | 角色 | 公司 | +| ------------------- | ---------------------------------------------------------- | ----------- | -------- | +| 张亮 | [@zhangliangboy](https://github.com/zhangliangboy) | Maintainer | 滴滴出行 | +| 谢鹏 | [@PenceXie](https://github.com/PenceXie) | Maintainer | 滴滴出行 | +| 赵情融 | [@zqrferrari](https://github.com/zqrferrari) | Maintainer | 滴滴出行 | +| 石臻臻 | [@shirenchuang](https://github.com/shirenchuang) | Maintainer | 滴滴出行 | +| 曾巧 | [@ZQKC](https://github.com/ZQKC) | Maintainer | 滴滴出行 | +| 孙超 | [@lucasun](https://github.com/lucasun) | Maintainer | 滴滴出行 | +| 洪华驰 | [@brodiehong](https://github.com/brodiehong) | Maintainer | 滴滴出行 | +| 许喆 | [@potaaaaaato](https://github.com/potaaaaaato) | Committer | 滴滴出行 | +| 郭宇航 | [@GraceWalk](https://github.com/GraceWalk) | Committer | 滴滴出行 | +| 李伟 | [@velee](https://github.com/velee) | Committer | 滴滴出行 | +| 张占昌 | [@zzccctv](https://github.com/zzccctv) | Committer | 滴滴出行 | +| 王东方 | [@wangdongfang-aden](https://github.com/wangdongfang-aden) | Committer | 滴滴出行 | +| 王耀波 | [@WYAOBO](https://github.com/WYAOBO) | Committer | 滴滴出行 | +| 赵寅锐 | [@ZHAOYINRUI](https://github.com/ZHAOYINRUI) | Maintainer | 字节跳动 | +| haoqi123 | [@haoqi123](https://github.com/haoqi123) | Contributor | 前程无忧 | +| chaixiaoxue | [@chaixiaoxue](https://github.com/chaixiaoxue) | Contributor | SYNNEX | +| 陆晗 | [@luhea](https://github.com/luhea) | Contributor | 竞技世界 | +| Mengqi777 | [@Mengqi777](https://github.com/Mengqi777) | Contributor | 腾讯 | +| ruanliang-hualun | [@ruanliang-hualun](https://github.com/ruanliang-hualun) | Contributor | 网易 | +| 17hao | [@17hao](https://github.com/17hao) | Contributor | | +| Huyueeer | [@Huyueeer](https://github.com/Huyueeer) | Contributor | INVENTEC | +| lomodays207 | [@lomodays207](https://github.com/lomodays207) | Contributor | 建信金科 | +| Super .Wein(星痕) | [@superspeedone](https://github.com/superspeedone) | Contributor | 韵达 | +| Hongten | [@Hongten](https://github.com/Hongten) | Contributor | Shopee | +| 徐正熙 | [@hyper-xx)](https://github.com/hyper-xx) | Contributor | 滴滴出行 | +| RichardZhengkay | [@RichardZhengkay](https://github.com/RichardZhengkay) | Contributor | 趣街 | +| 罐子里的茶 | [@gzldc](https://github.com/gzldc) | Contributor | 道富 | +| 陈忠玉 | [@paula](https://github.com/chenzhongyu11) | Contributor | 平安产险 | +| 杨光 | [@yaangvipguang](https://github.com/yangvipguang) | Contributor | +| 王亚聪 | [@wangyacongi](https://github.com/wangyacongi) | Contributor | +| Yang Jing | [@yangbajing](https://github.com/yangbajing) | Contributor | | +| 刘新元 Liu XinYuan | [@Liu-XinYuan](https://github.com/Liu-XinYuan) | Contributor | | +| Joker | [@LiubeyJokerQueue](https://github.com/JokerQueue) | Contributor | 丰巢 | +| Eason Lau | [@Liubey](https://github.com/Liubey) | Contributor | | +| hailanxin | [@hailanxin](https://github.com/hailanxin) | Contributor | | +| Qi Zhang | [@zzzhangqi](https://github.com/zzzhangqi) | Contributor | 好雨科技 | +| fengxsong | [@fengxsong](https://github.com/fengxsong) | Contributor | | +| 谢晓东 | [@Strangevy](https://github.com/Strangevy) | Contributor | 花生日记 | +| ZhaoXinlong | [@ZhaoXinlong](https://github.com/ZhaoXinlong) | Contributor | | +| xuehaipeng | [@xuehaipeng](https://github.com/xuehaipeng) | Contributor | | +| 孔令续 | [@mrazkong](https://github.com/mrazkong) | Contributor | | +| pierre xiong | [@pierre94](https://github.com/pierre94) | Contributor | | +| PengShuaixin | [@PengShuaixin](https://github.com/PengShuaixin) | Contributor | | +| 梁壮 | [@lz](https://github.com/silent-night-no-trace) | Contributor | | +| 张晓寅 | [@ahu0605](https://github.com/ahu0605) | Contributor | 电信数智 | +| 黄海婷 | [@Huanghaiting](https://github.com/Huanghaiting) | Contributor | 云徙科技 | +| 任祥德 | [@RenChauncy](https://github.com/RenChauncy) | Contributor | 探马企服 | diff --git a/docs/contributer_guide/开发者名单.md b/docs/contributer_guide/开发者名单.md deleted file mode 100644 index 3f2c708d..00000000 --- a/docs/contributer_guide/开发者名单.md +++ /dev/null @@ -1,6 +0,0 @@ - -开源贡献者证书发放名单(定期更新) - - -贡献者名单请看:[贡献者名单](https://doc.knowstreaming.com/product/10-contribution#106-贡献者名单) - diff --git a/docs/contributer_guide/贡献流程.md b/docs/contributer_guide/贡献流程.md deleted file mode 100644 index 42679379..00000000 --- a/docs/contributer_guide/贡献流程.md +++ /dev/null @@ -1,6 +0,0 @@ - - -
-
- -请点击:[贡献流程](https://doc.knowstreaming.com/product/10-contribution#102-贡献流程) \ No newline at end of file