yoko版本PR规范

本文档目前应用于我的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.nameuser.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
#Bugbug
#Feature新功能,新特性
#Performance性能
#Refactor-架构、设计方面
#Test测试
#Questionx疑问
#Need doc-需要作者补充文档
#Roadmapx作者自己提出来的一些待完成项
#Duplicatex和之前的issue重复
*In process-处理中。比如正在编写代码实现
*Waiting reply等待提出Issues和PRs的人的回复
*Answered-已给出提问者满意的解答
*Solved-已解决。比如特性已支持等
*PR acceptedxPR已经被合并进主分支中
*Invalid PRx被拒绝的PR
*Open another PRx建议重提PR,老PR直接关闭
*Indefinite delayx无限期延迟,比如不确定啥时候会支持的特性

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

0%