Skip to content

Commit 4852c01

Browse files
zengqiaoZQKC
zengqiao
authored and
ZQKC
committed
[Feature]补充贡献代码相关文档(#947)
1、补充贡献者名单，如有遗漏，辛苦告知； 2、补充贡献指南；
1 parent 3d6f405 commit 4852c01

File tree

10 files changed

+360
-12
lines changed

10 files changed

+360
-12
lines changed

‎docs/contribute_guide/assets/分支管理.drawio‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<mxfile host="65bd71144e">
2+
<diagram id="vxzhwhZdNVAY19FZ4dgb" name="Page-1">
3+
<mxGraphModel dx="1194" dy="733" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0"/>
6+
<mxCell id="1" parent="0"/>
7+
<mxCell id="4" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;startArrow=none;strokeWidth=2;strokeColor=#6666FF;" edge="1" parent="1" source="16">
8+
<mxGeometry relative="1" as="geometry">
9+
<mxPoint x="200" y="540" as="targetPoint"/>
10+
</mxGeometry>
11+
</mxCell>
12+
<mxCell id="7" style="edgeStyle=none;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;strokeColor=#33FF33;strokeWidth=2;" edge="1" parent="1" source="2">
13+
<mxGeometry relative="1" as="geometry">
14+
<mxPoint x="360" y="240" as="targetPoint"/>
15+
</mxGeometry>
16+
</mxCell>
17+
<mxCell id="5" style="edgeStyle=none;html=1;startArrow=none;strokeColor=#33FF33;strokeWidth=2;" edge="1" parent="1">
18+
<mxGeometry relative="1" as="geometry">
19+
<mxPoint x="200" y="400" as="targetPoint"/>
20+
<mxPoint x="360" y="360" as="sourcePoint"/>
21+
</mxGeometry>
22+
</mxCell>
23+
<mxCell id="3" value="C3" style="verticalLabelPosition=middle;verticalAlign=middle;html=1;shape=mxgraph.flowchart.on-page_reference;labelPosition=center;align=center;strokeColor=#FF8000;strokeWidth=2;" vertex="1" parent="1">
24+
<mxGeometry x="340" y="280" width="40" height="40" as="geometry"/>
25+
</mxCell>
26+
<mxCell id="18" style="edgeStyle=none;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;endArrow=none;endFill=0;strokeColor=#FF8000;strokeWidth=2;" edge="1" parent="1" source="8" target="3">
27+
<mxGeometry relative="1" as="geometry"/>
28+
</mxCell>
29+
<mxCell id="8" value="fix_928" style="rounded=1;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;" vertex="1" parent="1">
30+
<mxGeometry x="320" y="40" width="80" height="40" as="geometry"/>
31+
</mxCell>
32+
<mxCell id="9" value="github_master" style="rounded=1;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;" vertex="1" parent="1">
33+
<mxGeometry x="160" y="40" width="80" height="40" as="geometry"/>
34+
</mxCell>
35+
<mxCell id="10" value="" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;endArrow=classic;startArrow=none;endFill=1;strokeWidth=2;strokeColor=#6666FF;" edge="1" parent="1" source="11" target="2">
36+
<mxGeometry relative="1" as="geometry">
37+
<mxPoint x="200" y="640" as="targetPoint"/>
38+
<mxPoint x="200" y="80" as="sourcePoint"/>
39+
</mxGeometry>
40+
</mxCell>
41+
<mxCell id="2" value="C2" style="verticalLabelPosition=middle;verticalAlign=middle;html=1;shape=mxgraph.flowchart.on-page_reference;labelPosition=center;align=center;strokeColor=#6666FF;strokeWidth=2;" vertex="1" parent="1">
42+
<mxGeometry x="180" y="200" width="40" height="40" as="geometry"/>
43+
</mxCell>
44+
<mxCell id="12" value="" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;endArrow=classic;endFill=1;strokeWidth=2;strokeColor=#6666FF;" edge="1" parent="1" source="9" target="11">
45+
<mxGeometry relative="1" as="geometry">
46+
<mxPoint x="200" y="200" as="targetPoint"/>
47+
<mxPoint x="200" y="80" as="sourcePoint"/>
48+
</mxGeometry>
49+
</mxCell>
50+
<mxCell id="11" value="C1" style="verticalLabelPosition=middle;verticalAlign=middle;html=1;shape=mxgraph.flowchart.on-page_reference;labelPosition=center;align=center;strokeColor=#6666FF;strokeWidth=2;" vertex="1" parent="1">
51+
<mxGeometry x="180" y="120" width="40" height="40" as="geometry"/>
52+
</mxCell>
53+
<mxCell id="23" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;exitPerimeter=0;endArrow=none;endFill=0;strokeColor=#FF8000;strokeWidth=2;" edge="1" parent="1" source="3">
54+
<mxGeometry relative="1" as="geometry">
55+
<mxPoint x="360" y="360" as="targetPoint"/>
56+
<mxPoint x="360" y="400" as="sourcePoint"/>
57+
</mxGeometry>
58+
</mxCell>
59+
<mxCell id="17" value="" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;startArrow=none;endArrow=none;strokeWidth=2;strokeColor=#6666FF;" edge="1" parent="1" source="2" target="16">
60+
<mxGeometry relative="1" as="geometry">
61+
<mxPoint x="200" y="640" as="targetPoint"/>
62+
<mxPoint x="200" y="240" as="sourcePoint"/>
63+
</mxGeometry>
64+
</mxCell>
65+
<mxCell id="16" value="C4" style="verticalLabelPosition=middle;verticalAlign=middle;html=1;shape=mxgraph.flowchart.on-page_reference;labelPosition=center;align=center;strokeColor=#6666FF;strokeWidth=2;" vertex="1" parent="1">
66+
<mxGeometry x="180" y="440" width="40" height="40" as="geometry"/>
67+
</mxCell>
68+
<mxCell id="22" value="Tag-v3.2.0" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;fillColor=none;strokeColor=none;" vertex="1" parent="1">
69+
<mxGeometry x="100" y="120" width="80" height="40" as="geometry"/>
70+
</mxCell>
71+
<mxCell id="24" value="Tag-v3.2.1" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;fillColor=none;strokeColor=none;" vertex="1" parent="1">
72+
<mxGeometry x="100" y="440" width="80" height="40" as="geometry"/>
73+
</mxCell>
74+
<mxCell id="27" value="切换到主分支：git checkout github_master" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;" vertex="1" parent="1">
75+
<mxGeometry x="520" y="90" width="240" height="30" as="geometry"/>
76+
</mxCell>
77+
<mxCell id="34" style="edgeStyle=none;html=1;exitX=0;exitY=0;exitDx=0;exitDy=0;entryX=0.855;entryY=0.145;entryDx=0;entryDy=0;entryPerimeter=0;dashed=1;dashPattern=8 8;fontSize=18;endArrow=none;endFill=0;" edge="1" parent="1" source="28" target="2">
78+
<mxGeometry relative="1" as="geometry"/>
79+
</mxCell>
80+
<mxCell id="28" value="主分支拉最新代码：git pull" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;" vertex="1" parent="1">
81+
<mxGeometry x="520" y="120" width="160" height="30" as="geometry"/>
82+
</mxCell>
83+
<mxCell id="35" style="edgeStyle=none;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;dashed=1;dashPattern=8 8;fontSize=18;endArrow=none;endFill=0;" edge="1" parent="1" source="29">
84+
<mxGeometry relative="1" as="geometry">
85+
<mxPoint x="270" y="225" as="targetPoint"/>
86+
</mxGeometry>
87+
</mxCell>
88+
<mxCell id="29" value="基于主分支拉新分支：git checkout -b fix_928" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;" vertex="1" parent="1">
89+
<mxGeometry x="520" y="210" width="250" height="30" as="geometry"/>
90+
</mxCell>
91+
<mxCell id="37" style="edgeStyle=none;html=1;exitX=0;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;entryPerimeter=0;dashed=1;dashPattern=8 8;fontSize=18;endArrow=none;endFill=0;" edge="1" parent="1" source="30" target="3">
92+
<mxGeometry relative="1" as="geometry"/>
93+
</mxCell>
94+
<mxCell id="30" value="提交代码：git commit -m &quot;[Optimize]优化xxx问题(#928)&quot;" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;" vertex="1" parent="1">
95+
<mxGeometry x="520" y="270" width="320" height="30" as="geometry"/>
96+
</mxCell>
97+
<mxCell id="31" value="提交到自己远端仓库：git push --set-upstream origin fix_928" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;" vertex="1" parent="1">
98+
<mxGeometry x="520" y="300" width="334" height="30" as="geometry"/>
99+
</mxCell>
100+
<mxCell id="38" style="edgeStyle=none;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;dashed=1;dashPattern=8 8;fontSize=18;endArrow=none;endFill=0;" edge="1" parent="1" source="32">
101+
<mxGeometry relative="1" as="geometry">
102+
<mxPoint x="280" y="380" as="targetPoint"/>
103+
</mxGeometry>
104+
</mxCell>
105+
<mxCell id="32" value="GitHub页面发起Pull Request请求，管理员合入主仓库" style="rounded=0;whiteSpace=wrap;html=1;absoluteArcSize=1;arcSize=14;strokeWidth=0;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;" vertex="1" parent="1">
106+
<mxGeometry x="520" y="360" width="300" height="30" as="geometry"/>
107+
</mxCell>
108+
</root>
109+
</mxGraphModel>
110+
</diagram>
111+
</mxfile>

‎docs/contribute_guide/assets/分支管理.png‎

63.6 KB
Loading

‎docs/contribute_guide/assets/环境初始化.jpg‎

180 KB
Loading

‎docs/contribute_guide/assets/申请合并.jpg‎

79.9 KB
Loading

‎docs/contribute_guide/assets/问题认领.jpg‎

631 KB
Loading

docs/contributer_guide/代码规范.md renamed to docs/contribute_guide/代码规范.md

File renamed without changes.

‎docs/contribute_guide/贡献指南.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# 贡献指南
2+
3+
- [贡献指南](#贡献指南)
4+
- [1、行为准则](#1行为准则)
5+
- [2、仓库规范](#2仓库规范)
6+
- [2.1、Issue 规范](#21issue-规范)
7+
- [2.2、Commit-Log 规范](#22commit-log-规范)
8+
- [2.3、Pull-Request 规范](#23pull-request-规范)
9+
- [3、操作示例](#3操作示例)
10+
- [3.1、初始化环境](#31初始化环境)
11+
- [3.2、认领问题](#32认领问题)
12+
- [3.3、处理问题 \& 提交解决](#33处理问题--提交解决)
13+
- [3.4、请求合并](#34请求合并)
14+
- [4、常见问题](#4常见问题)
15+
- [4.1、如何将多个 Commit-Log 合并为一个？](#41如何将多个-commit-log-合并为一个)
16+
17+
18+
---
19+
20+
21+
欢迎 👏🏻 👏🏻 👏🏻 来到 `KnowStreaming`。本文档是关于如何为 `KnowStreaming` 做出贡献的指南。如果您发现不正确或遗漏的内容, 请留下您的意见/建议。
22+
23+
24+
---
25+
26+
27+
## 1、行为准则
28+
29+
请务必阅读并遵守我们的：[行为准则](https://github.com/didi/KnowStreaming/blob/master/CODE_OF_CONDUCT.md)。
30+
31+
32+
## 2、仓库规范
33+
34+
### 2.1、Issue 规范
35+
36+
按要求，在 [创建Issue](https://github.com/didi/KnowStreaming/issues/new/choose) 中创建ISSUE即可。
37+
38+
需要重点说明的是：
39+
- 提供出现问题的环境信息，包括使用的系统，使用的KS版本等；
40+
- 提供出现问题的复现方式；
41+
42+
43+
### 2.2、Commit-Log 规范
44+
45+
`Commit-Log` 包含三部分 `Header`、`Body`、`Footer`。其中 `Header` 是必须的，格式固定，`Body` 在变更有必要详细解释时使用。
46+
47+
48+
**1、`Header` 规范**
49+
50+
`Header` 格式为 `[Type]Message(#IssueID)`， 主要有三部分组成，分别是`Type`、`Message`、`IssueID`，
51+
52+
- `Type`：说明这个提交是哪一个类型的，比如有 Bugfix、Feature、Optimize等；
53+
- `Message`：说明提交的信息，比如修复xx问题；
54+
- `IssueID`：该提交，关联的Issue的编号；
55+
56+
57+
实际例子：[`[Bugfix]修复新接入的集群，Controller-Host不显示的问题(#927)`](https://github.com/didi/KnowStreaming/pull/933/commits)
58+
59+
60+
61+
**2、`Body` 规范**
62+
63+
一般不需要，如果解决了较复杂问题，或者代码较多，需要 `Body` 说清楚解决的问题，解决的思路等信息。
64+
65+
---
66+
67+
**3、实际例子**
68+
69+
```
70+
[Optimize]优化 MySQL & ES 测试容器的初始化(#906)
71+
72+
主要的变更
73+
1、knowstreaming/knowstreaming-manager 容器；
74+
2、knowstreaming/knowstreaming-mysql 容器调整为使用 mysql:5.7 容器；
75+
3、初始化 mysql:5.7 容器后，增加初始化 MySQL 表及数据的动作；
76+
77+
被影响的变更：
78+
1、移动 km-dist/init/sql 下的MySQL初始化脚本至 km-persistence/src/main/resource/sql 下，以便项目测试时加载到所需的初始化 SQL；
79+
2、删除无用的 km-dist/init/template 目录；
80+
3、因为 km-dist/init/sql 和 km-dist/init/template 目录的调整，因此也调整 ReleaseKnowStreaming.xml 内的文件内容；
81+
```
82+
83+
84+
**TODO : 后续有兴趣的同学，可以考虑引入 Git 的 Hook 进行更好的 Commit-Log 的管理。**
85+
86+
87+
### 2.3、Pull-Request 规范
88+
89+
详细见：[PULL-REQUEST 模版](../../.github/PULL_REQUEST_TEMPLATE.md)
90+
91+
需要重点说明的是：
92+
93+
- <font color=red > 任何 PR 都必须与有效 ISSUE 相关联。否则， PR 将被拒绝；</font>
94+
- <font color=red> 一个分支只修改一件事，一个 PR 只修改一件事；</b></font>
95+
96+
---
97+
98+
99+
## 3、操作示例
100+
101+
本节主要介绍对 `KnowStreaming` 进行代码贡献时，相关的操作方式及操作命令。
102+
103+
名词说明：
104+
- 主仓库：https://github.com/didi/KnowStreaming 这个仓库为主仓库。
105+
- 分仓库：Fork 到自己账号下的 KnowStreaming 仓库为分仓库；
106+
107+
108+
### 3.1、初始化环境
109+
110+
1. `Fork KnowStreaming` 主仓库至自己账号下，见 https://github.com/didi/KnowStreaming 地址右上角的 `Fork` 按钮；
111+
2. 克隆分仓库至本地：`git clone [email protected]:xxxxxxx/KnowStreaming.git`，该仓库的简写名通常是`origin`；
112+
3. 添加主仓库至本地：`git remote add upstream https://github.com/didi/KnowStreaming`，`upstream`是主仓库在本地的简写名，可以随意命名，前后保持一致即可；
113+
4. 拉取主仓库代码：`git fetch upstream`；
114+
5. 拉取分仓库代码：`git fetch origin`；
115+
6. 将主仓库的`master`分支，拉取到本地并命名为`github_master`：`git checkout -b upstream/master`；
116+
117+
最后，我们来看一下初始化完成之后的大致效果，具体如下图所示：
118+
![环境初始化](./assets/环境初始化.jpg)
119+
120+
121+
至此，我们的环境就初始化好了。后续，`github_master` 分支就是主仓库的`master`分支，我们可以使用`git pull`拉取该分支的最新代码，还可以使用`git checkout -b xxx`拉取我们想要的分支。
122+
123+
124+
125+
### 3.2、认领问题
126+
127+
在文末评论说明自己要处理该问题即可，具体如下图所示：
128+
129+
![问题认领](./assets/问题认领.jpg)
130+
131+
132+
### 3.3、处理问题 & 提交解决
133+
134+
本节主要介绍一下处理问题 & 提交解决过程中的分支管理，具体如下图所示：
135+
136+
![分支管理](./assets/分支管理.png)
137+
138+
1. 切换到主分支：`git checkout github_master`；
139+
2. 主分支拉最新代码：`git pull`；
140+
3. 基于主分支拉新分支：`git checkout -b fix_928`；
141+
4. 提交代码，安装commit的规范进行提交，例如：`git commit -m "[Optimize]优化xxx问题(#928)"`；
142+
5. 提交到自己远端仓库：`git push --set-upstream origin fix_928`；
143+
6. `GitHub` 页面发起 `Pull Request` 请求，管理员合入主仓库。这部分详细见下一节；
144+
145+
146+
### 3.4、请求合并
147+
148+
代码在提交到 `GitHub` 分仓库之后，就可以在 `GitHub` 的网站创建 `Pull Request`，申请将代码合入主仓库了。 `Pull Request` 具体见下图所示：
149+
150+
![申请合并](./assets/申请合并.jpg)
151+
152+
153+
154+
[Pull Request 创建的例子](https://github.com/didi/KnowStreaming/pull/945)
155+
156+
157+
158+
---
159+
160+
161+
## 4、常见问题
162+
163+
### 4.1、如何将多个 Commit-Log 合并为一个？
164+
165+
可以使用 `git rebase -i` 命令进行解决。
166+
167+

0 commit comments

Comments
 (0)