开源贡献的一些规范

一、PR流程

选择社区项目进行 Fork，开发工作应当放在自己的仓库中，个人仓库的 master 分支负责与上游仓库进行同步。

Clone 个人仓库的项目，在本地开发中，可以同时添加上游仓库源；修改代码时，从最新的 master checkout 到新的临时分支（eg：tmp-branch），在该分支上进行开发，之后 push 到远程个人仓库的一个临时分支（可以直接和本地分支名相同）上。

1
2
3
4
5
# 添加上游仓库
git remote add upstream https://github.com/xxx/xxx.git

# 创建并切换到新的分支
git checkout -b tmp-branch

此时进入上游仓库，可以发现来自个人仓库临时分支的 pull request 提示，点击并填写提交信息，发起合并请求。自动化测试工具通过后，就只需等待社区人员审查，交流通过后便可以将自己的修改合进原项目。此时可以直接删除个人仓库中的临时分支。

下次修改前需要先将个人仓库的 master 分支与上游仓库进行同步。

一般在社区的首次 PR 请求，会要求贡献者签署 CLA，按照相应的提示操作即可。一些社区也会提供 playground 项目，可以在该项目中练习 PR 的流程，并完成签署 CLA。

需要注意的是，提交 PR 请求，通过后会根据 PR 的提交信息创建一个新的 commit 点，PR 中个人分支上的多条新 commit 点并不会出现在上游仓库的主分支上。

二、commit 规范

Angular 提交信息规范

需要一定的规范来约束开发人员的 commit 信息格式，其中，Angular提交信息规范是一种非常受开发人员欢迎的 commit 信息规范。

每条 commit message 都由 header、body 和 footer 组成。而 header 包括 type、scope 和 subject：

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

type 必须是以下值之一：

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

subject 要求：

  • 以动词开头，使用第一人称现在时，比如 change，而不是 changed 或 changes
  • 不要大写首字母
  • 不在末尾添加句号

commitizen

借助 commitizen 可以方便地规范输入 commit 信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 全局安装
npm install -g commitizen
```  

另一方面，需要安装适配器进行标准提交提示，此处选择 `cz-conventional-changelog`。

```sh
# 全局安装
npm install -g cz-conventional-changelog
# 在根目录下添加文件 .czrc，内容如下
{ "path": "cz-conventional-changelog" }


# 本地安装
npm install --save-dev cz-conventional-changelog
# 在package.json中添加配置
"config": {
   "commitizen": {
     "path": "cz-conventional-changelog"
   }
 }

此时，可以使用 cz 命令代替 git commit，进行规范化 commit 提交。

三、社区术语

缩写 英文 中文
PR Pull request 拉取请求
BTW By the way 顺便说一句
WIP Work in progress, do not merge yet 进行中暂时不要合并
LGTM Looks good to me 在我看来很好
PTAL Please take a look 帮我看下，请别人 review 自己的 PR
CC Carbon copy 抄送
FYI For your information 供你参考
RFC Request for comments 我觉得这个想法很好, 我们来一起讨论下
IIRC If I recall correctly 如果我没记错
ACK Acknowledgement 认可
NACK/NAK Negative acknowledgement 不认可

参考：

  1. Github 常用社交用语 -腾讯云开发者社区-腾讯云 (tencent.com)
  2. Angular 提交信息规范
  3. 使用标准commit生成changelog标准化 - 简书 (jianshu.com)
#OpenSource #Git #commitizen
开源贡献的一些规范
https://kaysonyu.github.io/2024/09/Open-Source/
Author
Yu Kang
Posted on
September 7, 2024
Licensed under