提交贡献代码
介绍从 github 发起 pull requests 和提交代码的流程。
Fork 仓库
访问 https://github.com/yunionio/cloudpods ,将仓库 fork 到自己的 github 用户下。
Clone 源码
clone 自己 fork 的仓库,并设置 upstream 为源仓库。
$ git clone https://github.com/<your_name>/cloudpods
$ cd cloudpods
$ git remote add upstream https://github.com/yunionio/cloudpods
提交代码流程
1. 从 master checkout 出 feature 或者 bugfix 分支
# checkout 新分支
$ git fetch upstream --tags
# 下面假设新的分支名为 'feature/implement-x'
# 分支名应该有语义性,描述这次开发要实现或者修复什么
$ git checkout -b feature/implement-x upstream/master
2. 在新的分支上进行开发
所有的代码修改,都在新的分支上进行。
如果不熟悉 git 相关的操作,可参考这个文档先学习 git 的基本操作:Git-Tutorials。
3. 开发完成后,进行提交PR前的准备操作
# 同步远程 upstream master 代码
$ git fetch upstream
# 有冲突则解决冲突
$ git rebase upstream/master
# push 分支到自己的 repo
$ git push origin feature/implement-x
4. 在GitHub的Web界面完成提交PR的流程
- 提完 PR 后请求相关开发人员 review,并设置Labels来表明提交的代码属于哪一个模块或者哪几个模块。
- 或者通过添加评论的方式来完成上一步;评论 "/cc" 并 @ 相关人员完成设置reviewer,评论 /area 模块名称 标记此次改动所属的模块。
所有Label都可以在issues—Labels下查询到,带area/前缀的Label均可以使用评论"/area"的形式添加
5. cherry-pick 代码
如果是 bugfix 或者需要合并到之前 release 分支的 feature PR,需要额外使用脚本将此PR cherry-pick 到对应的 release 分支
# 自行下载安装 github 的 cli 工具:https://github.com/github/hub
# macOS 使用: brew install hub
# Debian: sudo apt install hub
# 二进制安装: https://github.com/github/hub/releases
# 设置github的用户名
# 可已把该环境变量放到 ~/.bashrc 里面,如果使用的 zsh 则放到 ~/.zshrc 里面
$ export GITHUB_USER=<your_username>
# 访问这个连接添加自己的访问 token:https://github.com/settings/tokens
# 设置github个人token
$ export GITHUB_TOKEN=<your_access_token>
# 使用脚本自动 cherry-pick PR 到 release 分支
# 比如现在有一个提交的PR的编号为17561,要把它合并到 release/3.10
$ ./scripts/cherry_pick_pull.sh upstream/release/3.10 17561
# cherry pick 可能会出现冲突,冲突时开另外一个 terminal,解决好冲突,再输入 'y' 进行提交
$ git add xxx # 解决完冲突后
$ git am --continue
# 回到执行 cherry-pick 脚本的 terminal 输入 'y' 即可
去 upstream 的 PR 页面, 就能看到自动生成的 cherry-pick PR,上面操作的PR的标题前缀就应该为:Automated cherry pick of #17561
,然后重复 PR review 流程合并到 release
提交 git 代码后需要书写 commit 内容,规范请参考: Git 提交内容规范。
开发效率提升推荐配置
上述的提 PR 流程使用到了很多命令行操作,特别是在执行 ./scripts/cherry_pick_pull.sh
脚本的时候会输入很多字符。以及每次执行该脚本都需要输入 github 的 token。重复执行这些操作会让人觉得浪费时间。
下面提供一些配置和工具,可以提升一些命令行下的开发效率,请根据自己的实际需要选择配置。
避免每次输入 github 认证信息
每次 push 代码或者执行 cherry_pick_pull.sh 脚本的时候,都需要输入 github 账号和 token,可以配置 git credential cache 缓存输入的认证信息。
# tells Git to keep your password cached in memory for a particular amount of minutes
$ git config --global credential.helper "cache --timeout=86400"
另外如果想实现 github 自动登陆,可以创建 ~/.netrc
文件,里面配置 github 用户名和 token。
$ cat ~/.netrc
machine github.com
login $github_user
password $github_token
提升命令重复输入效率
在 shell 里面重复输入命令,可以通过'上键'或者'Ctrl-p' 输入上一条执行过的命令。
另外一个好用的功能是输入 'Ctrl-r' 就会进入 shell 的已输入命令查找模式,然后在这个模式里面输入之前命令的关键字,就可以进行查找。如果不匹配重复按 'Ctrl-r' 就会继续找,找到想要的命令后,按下 'Enter' 就可以重复输入之前输入的命令。合理的使用 'Ctrl-r' 可以极大的提升重复相关命令的输入效率。
另外推荐安装一个不错的命令行模糊查找工具(command-line fuzzy finder),叫做 fzf ,参考该文档安装 fzf installation。安装配置完该工具后,再使用 'Ctrl-r' ,就会进入一个命令行模糊查找的模式,比 shell 自带的 'Ctrl-r' 命令查找要好用。
另外关于命令行下的使用思想,非常建议阅读这篇文章:The Art of Command Line。
美化 shell
在 linux 和 macOS 系统自带的 shell 默认是 bash,进入 git 代码仓库,$PS1 是没有显示 git branch 等信息的,可以使用下面的方式美化系统的 shell,提供更舒适的命令行操作体验。
下面提供2种方式美化 shell ,请根 据自己需要选择其一就行:
-
bash + oh-my-bash 的方式
- 系统自带 bash,所以只需要参考 oh-my-bash 安装文档配置即可。
-
zsh + ohmyzsh:这种方式需要安装 zsh 和 ohmyzsh 插件,zsh 和 bash 类似都是 shell ,但提供更丰富的特性,结合 ohmyzsh 插件使用是很多开发者的选择
- zsh 安装参考文档: 安装 zsh
- ohmyzsh 插件安装参考: 安装 ohmyzsh
- 另外需要注意的是 zsh 的默认配置文件在
~/.zshrc
,如果之前在~/.bashrc
里面加了一些环境变量,需要迁移到~/.zshrc
里面。