【Git】一个流畅的开源贡献流程

Git Workflow 评论

由本人的有道云笔记搬运到个人网站，创作日期：2023年3月20日

教练……我想开源

一直想参加一个开源项目，丰富自己GitHub账号头衔的同时还能学到一些知识。目前定位到了两个自己非常感兴趣的项目

  1. （国内项目）Paddle：百度飞桨深度学习框架
  2. （国际项目）Gradio：用Python构建机器学习网页APP
    在项目主页的 Issues 提出自己的问题

github开源仓库工作流

参考《A successful Git branching model》
Remote（main/）：所有人都共享的代码仓库

如果我们想进行开源贡献

  • 第一步就是建立一个“feature branch”。目前在Local上，main branch 和 feature branch 上面的内容都是一致的。当使用checkout命令后，硬盘会同步git指定branch下所有的源文件（切换就会改变硬盘当下空间内部的文件）
    如何正确提Issues
    在提Issues之前，一定要提前用关键字搜索看一下你想提出的问题是否已经存在。确定不存在后再进行提问

Paddle项目

文档贡献指南

以最近的一次合并提交为例：本次提交是添加了Tensor文件夹下的十个说明文档。

第一步：Fork仓库并Clone到本地加载

1
2
git clone https://github.com/<USERNAME>/docs
cd docs

第二步：Fork仓库并Clone到本地加载

docs 目前使用 Git 流分支模型进行开发，测试，发行和维护。
所有的 feature 和 bug fix 的开发工作都应该在一个新的分支上完成，一般从 develop 分支上创建新分支。
使用 git checkout -b 创建并切换到新分支。

1
2
git status  #查看一下当前分支目录是否clean
git checkout -b <创建并切换到的分支名称>

第三步：下载pre-commit工具（下载过就不用再下了）

一种检查模板格式是否匹配项目格式的预提交工具。

1
2
pip install pre-commit
pre-commit install

第四步：单次修改并提交都要运行pre-commit进行单元测试

  1. 通过指令 git status 进行状态的检查
  2. 通过 git add 将内容添加进准备提交的区域

git status

上面的状态空间中显示我 9 次修改中有 1 次进入了“暂存区”，此时就要使用pre-commit指令进行单元测试

pre-commit

上面在运行了pre-commit之后，除了红色以外区域显示是通过的部分。红色部分说明没有通过单元测试，这个报错说明Linux系统和Win系统的换行符不统一导致的格式问题，一般这种情况下pre-commit会自己进行修复，所以重新提交就可以解决

pre-commit

上面在进行了一次性的提交之后，pre-commit一次性将所有的文件进行了检查和修改，之后再进行一次 git add –update 就可以将更新修改后的文件合并至文件的缓存区内。

git add --update

解决步骤如上

pre-commit

在进行一次提交之后就可以看到所有单元测试已经通过了

在单元测试全部通过之后，可以正式填写提交说明了：

git commit

上面我提出的说明是“修改文档”。显示有 9 个文件被修改了， 20 行新增代码， 22 行删减代码。

提交：commit

之所以要运行 pre-commit 就是要为后面要执行的commit操作避免提前的冲突和麻烦

1
git commit -m "fix/add xxxx"

第五步：push

先确保已经同步过原始仓库的最新代码 https://github.com/PaddlePaddle/docs

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
➜  git remote
origin
➜  git remote -v
origin  https://github.com/USERNAME/docs (fetch)
origin  https://github.com/USERNAME/docs (push)

# origin 是 clone 的远程仓库的名字，也就是自己用户名下的 Paddle，接下来创建一个原始 Paddle 的仓库远程主机，命名为 upstream
➜  git remote add upstream https://github.com/PaddlePaddle/docs
➜  git remote
>>  origin
>>  upstream
-----------------------------------之前提交过了就可以跳到这一步---------------------------------------------

# 获取 upstream 的最新代码并更新当前分支

# 从 upstream 远程仓库获取最新的代码和提交历史，将本地仓库与远程仓库保持同步。
➜  git fetch upstream  

# 从 upstream 远程仓库 develop 分支中获取最新的代码和提交历史，并将其自动合并到当前本地分支。
➜  git pull upstream develop 

# Push 到远程仓库：也就是将本地修改推送到 GitHub 即： https://github.com/USERNAME/docs
# 将本地分支的提交推送到名为origin的远程仓库中的特定分支（<my-pr>）。
# 通过执行此命令，您可以将本地分支的修改上传到远程仓库，使得其他协作者可以查看和访问您的提交。
➜  git push origin <my-pr(第二步中取的名字)>

第六步：review & merge

我的第一次提交 https://github.com/PaddlePaddle/docs/pull/5747
几点小的总结：

  • 尽量把自己在做的过程中不确定的内容进行说明
  • 把疑问的地方进行复现
  • 每一轮的回复都要进行礼貌性的回答
  • 尽量把每一版的修改都进行分点的说明，第一做了XXX，第二做了XXXX……

小插曲：CheckPRTemplate 一定要规范

如果希望 Paddle 能够接受你的提交，至少需要满足以下三点：

  • 单元测试通过 —— Docs-NEW

  • 文档PR格式检测通过 —— CheckPRTemplate

  • 同意签署开源贡献者协议 —— license/cla
    一般Docs-NEW可能需要比较长的时间进行检测，偶尔也需要排队等待。所以这次我以为 CheckPRTemplat 也是一样需要等，但是等了整整一天时间……最后发现其实PR格式不是特别正确（虽然也有人格式不正确但通过了PR格式检测），最终参考 checkprtemplate 。修改后的格式如下：

    Paddle项目开源贡献要求的格式

修改之后秒过。

Gradio项目

一位同学进行的一个非常标准的开源参与流程：

  1. 提Issues。在这个过程中以项目管理者角度出发，顺带说明了四点问题：

    1. 是否已存在类似Issue。I have searched to see if a similar issue already exists.（我已经搜索过是否已经存在类似问题。）
    2. 描述你的问题和想添加的功能。Is your feature request related to a problem? Please describe.（您的功能请求是否与问题相关？请描述。）
    3. 提出解决方案。Describe the solution you’d like.（描述您想要的解决方案）
    4. 是否有前情提要。Additional context.（附加上下文）

    提问动机

  2. 请求合并Merge。在这个过程中以项目管理者角度出发，顺带说明了四点问题：

    1. relevant motivation.（相关动机）
    2. a summary of the change.（总结你做出的更改）
    3. which issue is fixed.（解决了Issue中的哪一个）
    4. any additional dependencies that are required for this change.（在本次变更中是否有其他依赖项）

    详细描述自己所做的工作

参考链接

  1. git commit之后，想撤销commit

    1
    git reset --soft HEAD^

  2. 视频链接

    1. 【如何正确地提github issue？开源项目作者来和你聊聊这个重要技能】
    2. 【十分钟学会正确的github工作流，和开源作者们使用同一套流程】
    3. 【freeCodeCamp | 如何在 GitHub 提交第一个 pull request】

  3. AIstudio上持久化安装pip包

    1. 提前运行 cd ~ && mkdir loca_data && ln -s local_data.local

  4. 十分钟学会正确的github工作流，和开源作者们使用同一套流程

    一套开源项目和部分企业都在使用的工作流

AndroidStudent & Coder

Happy Coding!