TTF基金会管理 TTF 开源项目贡献指南 (初稿)

陈恒捷 for TTF基金会 · September 28, 2019 · Last by 陈恒捷 replied at September 29, 2019 · 611 hits

为了方便更多的新同学能够按照统一的规范加入到 TTF 项目中,特制定此指南,便于大家采用统一的方式进行贡献。

认领任务

可以在项目的指定任务列表中(各项目的招募公告中会给出具体的任务列表),选定你想要参与贡献的任务,在任务底部评论说明 “认领此任务,预计xx月xx日完成”

执行任务

认领后,需要通过代码提交来完成此任务。此时我们需要遵循三个步骤:

  • fork 仓库
  • 开发+自测+提交代码
  • 提交 pull request

Fork 仓库

由于此时大家并没有对当前开源项目仓库进行修改的权限,因此需要通过 fork ,将此仓库复制一份到自己的名字下,从而得到一个自己有权限提交代码的仓库。

Fork 完毕后,会在自己的名下得到一个和原来开源项目仓库一模一样的仓库:

开发+自测+提交代码

当完成了 Fork 操作后,可以 clone 下自己的仓库代码,并在本地基于 master 建立新的分支,进行开发、自测,并在自测通过后提交代码到自己的远程仓库。

这部分应该是大家都比较熟悉的部分,没有什么特殊的点,此处就不特别展开了。

有一点特别说明一下:当这个任务时间比较长时,需要及时同步官方仓库 master 分支的代码至自己的开发分支,避免产生严重代码冲突。此时同步请使用 rebase 而非 merge 进行,避免引起太多的分叉。

示例:

# clone 自己 fork 出来的仓库
$ git clone git@github.com:chenhengjie123/httprunner.git
$ cd httprunner

# 自行开发并提交代码

# 添加官方仓库至远程仓库,名称为 upstream (中文意思是 上游
$ git remote add upstream git@github.com:httprunner/httprunner.git

# 确认添加成功
$ git remote -v
origin git@github.com:chenhengjie123/httprunner.git (fetch)
origin git@github.com:chenhengjie123/httprunner.git (push)
upstream git@github.com:httprunner/httprunner.git (fetch)
upstream git@github.com:httprunner/httprunner.git (push)

# 获取官方仓库最新提交记录(这一步操作不会改动本地任何代码,请放心)
$ git fetch upstream

# 把官方仓库中,比自己本地分支新的提交,以 rebase 的方式添加到自己的本地分支。若有冲突,请自行解决
$ git rebase upstream/master

# 把添加记录后的本地分支,push 到自己仓库中。此时最新代码同步完毕。
$ git push

提交 pull request

通过前一步骤,对应的修改代码已经放到了你自己 fork 出来的仓库里了,此时需要通过提交 pull request (后续简称 PR)来提交一个申请,把你的这部分修改代码合并到原来开源项目的仓库中。

当你的代码 push 到自己的远程仓库后,在 github 仓库首页,会见到一个自动提示,可以直接点击 【Compare & pull request】进入 PR 创建页面。

在 PR 创建页面,完成以下5项检查,最后点击 【Create Pull Request】提交你的修改。

提交完成后,将进入 PR 展示页面,你的 PR 将会出现在开源项目的 PR 列表中,并通知项目作者。

若希望你的 PR 做得更好,可以参考 (可选)特别技巧:压缩你的提交至一个

后续修改

PR 提交后,作者会进行 Review ,个别项目还会自动触发一些自动化检查和测试。若这些检查没有通过,会在 PR 页面上有对应提示,此时需要再次修改代码。

修改时,不需要重新提交 PR ,只需要直接在 PR 中自己仓库的分支进行修改,push,并在修改完毕后在 PR 中添加评论说明修改已提交即可。

另外,请特别注意,任何 PR 不应该存在和原有官方仓库的代码冲突。若存在,请自行修复。

完成任务

在 PR 检查通过,最终被作者合并时,恭喜你,任务完成啦!

此时可以在原来任务 issue 里面,添加如下评论,通知作者任务完成:

也再次恭喜你,这个开源项目的提交记录和贡献者名单里,都会有你的名字啦。

(可选)特别技巧:压缩你的提交至一个

为了让代码树更简洁,强烈推荐大家在提交 PR 前,先通过 rebase ,把自己的分支修改代码形成的提交数量,压缩成一个。

操作示例:

# 查看本地待提交 PR 的提交列表
$ git log --oneline
29c1099 (HEAD -> fix-issue-#200, origin/fix-issue-#200) fix: (示例)前一次修改有提交遗漏了,再提交一次
0258955 fix: (示例)修复 skipIf suite 不起作用的问题
f4a6ce9 (upstream/master, origin/master, origin/HEAD, master) Merge pull request #709 from httprunner/debugtalk-patch-doc
3570944 (upstream/debugtalk-patch-doc, origin/debugtalk-patch-doc) doc: add jsonpath link

# 假设前面的 f4a6ce9 是官方的最新代码,而 0258955 29c1099 是我们为了这次任务添加的2个提交。此时我们想把它合并成一个。
# 此时记住2个简单的规则:第一行提交前面的 pick 改为 rreword,表示重新编辑这次提交的 message ,下面的全部改为 f fixup,表示这次提交的变更合并到前一个提交中,且不保留原有的 message
$ git rebase -i f4a6ce9
r 0258955 fix: (示例)修复 skipIf suite 不起作用的问题
f 29c1099 fix: (示例)前一次修改有提交遗漏了,再提交一次

# 前面修改完毕后,如果你使用的是 vi/vim 编辑器,通过 :wq 保存你的变更。此时会再出来一个 vi/vim 编辑窗口,给你修改合并前面改为 r 开头那个提交的 message
fix: (示例)修复 skipIf suite 不起作用的问题

# message 修改完毕后,同样 :wq 保存。此时会退出 vi/vim 编辑器,并出现如下提示文字
[detached HEAD 5abe665] fix: (示例)修复 skipIf suite 不起作用的问题
Date: Sat Sep 28 21:23:43 2019 +0800
1 file changed, 4 insertions(+)
Successfully rebased and updated refs/heads/fix-issue-#200.

# 此时本地修改已完成,需要推到远程分支。由于刚才的 rebase 是修改历史记录的操作,直接 push 是会报错的(! [rejected]),需要强制 push
$ git push --force

特别提醒一下,在已经 push 过的分支上进行 rebase 修改已有记录,是一件破坏代码提交历史的事情。请务必确认此分支只有你一个人在上面开发,且此次 rebase 只修改这个分支特有的提交,不影响其它分支合并过来的提交。

若在公共分支上进行此操作,将会导致整个团队其它同学都无法 push 和 pull 代码,也无法正常合并分支,只能重新 clone 并重新修改代码。严重时人身安全可能无法保证,请务必留意。

反馈

目前这个指南还是个初稿,若大家觉得里面有什么不足,或者有更好的建议,也欢迎反馈~

如果觉得我的文章对您有用,请随意打赏。您的支持将鼓励我继续创作!
共收到 3 条回复 时间 点赞

准备pr前尽量跟作者说下自己的思路

为了让代码树更简洁,强烈推荐大家在提交 PR 前,先通过 rebase ,把自己的分支修改代码形成的提交数量,压缩成一个。

这种方法并不好,如果你的修改内容很多的话,这种方法只会让review更加困难。最好从commit msg的角度来解决这种问题。

xdf 如何给开源项目做贡献 中提及了此贴 29 Sep 10:33
williamfzc 回复

这个是另一个话题了。所以这里也只是推荐,并非强制要求。

对于贡献要求里带有 rebase 这一项的项目,大部分也同样会要求单个 PR 提交的东西不应该太复杂以至于影响 review 。若有这种情况,说明一次 PR 内容过多,需要拆开每个独立功能单独 PR 。

需要 Sign In 后方可回复, 如果你还没有账号请点击这里 Sign Up