为了方便更多的新同学能够按照统一的规范加入到 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 改为 r（reword，表示重新编辑这次提交的 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 并重新修改代码。严重时人身安全可能无法保证，请务必留意。

反馈

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