yoko版本PR规范

发表于 | 分类于
| 字数统计: 1.3k

本文档目前应用于我的github项目：Go直播流媒体网络传输服务器lal，由于我在开源协助方面的经验有限，所以本文档还在不断完善中。

包含的内容：

  • PR规范
  • commit规范
  • 代码风格规范
  • 注释规范
  • label of Issues and PRs

首先大前提，repo原作者拥有一票否决PR的权利。
提PR前，建议先提issue，说说想法。这样PR的成功率比较高。

举两个反例：

  1. 同样的功能，可能已经有人在做（只是没有提交）
  2. 你想要修改的地方，作者可能正在范围性重构

以上等情况，可能导致你的工作变为多余无效，所以动手前，先沟通。

PR规范

  • 向原repo的master分支提交PR【强制！】
  • 提交PR前，确保在本地可以编译【强制！】
  • 提交PR时，git config的user.name和user.email必须和发起PR的账号一致【强制！】
  • 修改代码前，确保已同步原repo的master分支的最新代码，在这个代码基础上做修改【非强制】
  • 创建出一个独立的分支进行代码修改【非强制】
  • 一个功能，只提交一个PR，多个功能，应提交多个PR【非强制】
  • 提交PR前，新增加的代码，应增加相应的单元测试代码【非强制】
  • 提交PR前，确保通过所有的基础单元测试【非强制】
  • 一个PR尽量只包含一个commit【非强制】

commit规范

  • 每次commit需保证代码是可编译的【强制！】
  • commit message允许使用中文【非强制】
  • 一个commit不要包含多个功能【非强制】
  • commit message应包含修改类型以及简单描述，修改类型分类如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
feat     新功能
fix      bug修复
perf     不改变架构、对外表现的非功能性的性能优化
style    换行、空格、缩进、大小写等保证不会对功能造成影响的修改
log      日志
test     测试代码
doc      文档，或者代码注释修改
refactor 重构，不是其他类型就归到这一类
chore    编译、CI构建、打包等脚本相关的修改
patch    前次提交的补充

# 单个功能
# 举例1：
$git commit -m '[feat] httpflv pull拉流时，携带url参数'
# 举例2：
$git commit -m '[fix] hls写ts视频数据时，流中没有spspps导致崩溃'

# 多个功能（当然，最好还是分多次commit）
# 举例1：
$git commit -m '1. [doc] README 2. [chore] upgrade CI Go version to 1.9'
# 举例2：
$git commit
# 然后在打开的编辑器中填写描述内容，
# 首行写`messages:`，第二行空行，之后接内容，一行一个功能，以`- `开头：
#举例如下：
messages:

- [feat] lalserver增加回源功能
- [fix] 解析rtmp metadata时，兼容Object和Array两种外层格式
- [refactor] 重写了lalserver的中继转推的代码

代码风格规范

  • package包名全小写，不允许下划线【强制!】
  • 文件名全小写，允许使用下划线【强制!】
  • 多个单词组成的缩写，不使用驼峰【强制!】
    • 比如http是Hyper Text Transfer Protocol的缩写，我们写成http或HTTP，不写成Http
  • 单个单词的缩写，使用驼峰【强制!】
    • 比如req是request的缩写，我们写成req或者Req，不写成REQ
    • 也即，http request可以写成httpReq，HTTPReq，request http可以写成reqHTTP，ReqHTTP
  • 成员函数的对象命名，不使用this，obj【强制!】
  • 回调用的interface命名为xxxObserver，回调函数命名为onXxx（首字母是否大写根据是否需要对外暴露决定）【强制！】
  • 一个文件中，大写导出的函数放前面，小写函数放后面【非强制】

注释规范

  • 单行或多行注释，都只使用//，不使用`//`【强制!】**
  • //后面加一个空格再写注释内容【强制!】
  • 允许中文，如果使用了中文，标点符号使用全拼，比如，而不是,【非强制】
  • 只对需要注意的地方做解释型注释【非强制】
  • 注释why，不注释how。比如，能看懂代码在做啥，但不明白为什么要这么做时，可添加注释【非强制】
  • 当在架构、性能、可读性、可扩展性方面做出了取舍时，可添加注释【非强制】

label of Issues and PRs

大体分为两类，以#开头，表示类型，比如#Bug，以*开头，表示状态，作为Open和Closed的补充。

一般来说，一个label或PR可以有多个#类型的label，但是*类型的label只有一个。

由于github的设计是将Issues和PRs的label放一起管理，所以下面我也会说明label是供Issues还是PRs使用的。

labelIssuesPRsdetails
#Bug✔✔bug
#Feature✔✔新功能，新特性
#Performance✔✔性能
#Refactor✔-架构、设计方面
#Test✔✔测试
#Question✔x疑问
#Need doc✔-需要作者补充文档
#Roadmap✔x作者自己提出来的一些待完成项
#Duplicate✔x和之前的issue重复
*In process✔-处理中。比如正在编写代码实现
*Waiting reply✔✔等待提出Issues和PRs的人的回复
*Answered✔-已给出提问者满意的解答
*Solved✔-已解决。比如特性已支持等
*PR acceptedx✔PR已经被合并进主分支中
*Invalid PRx✔被拒绝的PR
*Open another PRx✔建议重提PR，老PR直接关闭
*Indefinite delay✔x无限期延迟，比如不确定啥时候会支持的特性

本文完，作者yoko，尊重劳动人民成果，转载请注明原文出处： https://pengrl.com/p/20070/

0%