如何给开源项目贡献代码-如何create pull request

第一次使用GitHub中的pull request功能，为开源项目贡献代码。一路磕磕碰碰，摸索了好久，所以特写此文档，简明通俗地总结 步骤 与 问题。我主要参考了这篇文章[1]。

默认已有GitHub账号，且ssh key等已配置好。如果有账号，却没有配置 也没有关系，在下面的操作中会出现问题，那根据问题去配置好key等信息 就可以了。

1. Why

• 为什么需要pull request的功能？
  有些开源项目的代码可能不完善，所以利用这个工具，可以将自己修改后的代码 提交给开源项目作者，让作者决定是否要修改或完善他自己本身的代码。
• pull request 的好处？
  方便好用，清晰明了。能自动地显示出 自己修改版本 与 作者版本 的区别，也就是显示修改的地方。

2. How

- 总体思路：

分两种情况：1）代码仓库管理者给你添加该仓库的写入权限，这样的话可以直接push
2）如果不能直接push（大多数情况），采用经典的fork & pull request来提交代码，下面主要讲述第2）种情况。
首先是 将对方fork到自己GitHub账号来，然后克隆代码到本地电脑来，在本地电脑上修改好代码后，再push到自己的GitHub上上面，最后就可以直接创建pull request了。

- 具体步骤:

1.先在本地创建一个空文件夹,里面准备放克隆过来的代码. --> 我在本地Downloads文件夹下创建了一个名为 gitMessagekit 的文件夹.

2.在"终端"中通过cd命令进入到gitMessagekit文件夹下–> cd /Users/自己电脑的用户名/Downloads/gitMessagekit (将"自己电脑的用户名"换成你自己的电脑的用户名).

3.在"终端"输入克隆命令 git clone 开源项目源代码的url. --> git clone https://github.com/MessageKit/MessageKit.git
【注意：这里的链接 是开源项目源代码的链接。】

4.进入到克隆所在的文件夹. --> cd /Users/自己电脑的用户名/Downloads/gitMessagekit/MessageKit
用查看命令查看一下开源项目都有多少个远程分支. --> git branch -a

5.找到自己要切换的远程分支,准备切换分支,假如在这里我要切换到 XXX 远程分支. --> git checkout remotes/origin/XXX
【这里切换到什么分支，那么就会下载到哪一个分支的代码到自己的电脑里。所以，如果需要最新的分支代码，那就选择对应最新最全的分支。】

6.基于远程分支，新建本地分支(***),2条命令. --> git branch XXX 和 git checkout XXX
【注意远程分支和本地分支的区别，名字一样，但是一个是远程，一个是本地。 branch是针对远程分支的，在远程分支上新建。如果是master一般都建过名字了。建议可以取别的名字，也可以不取。不取的话，要留心区别了。】

7.打开/Users/自己电脑的用户名/Downloads/gitMessagekit/MessageKit该路径下的代码,对代码进行修改.

8.添加修改. --> git add .

9.提交修改. --> git commit -m "fix 某某问题"
【注意是 双引号。 这里编译完之后 会出现 自己定义的branch名字，以防自己忘记。】

10.将本地代码关联到自己GitHub账户fork过的项目. --> git remote add upstream git@github.com:yanazeng/MessageKit.git
【注意：这里的链接是在 已经forked到自己账号的代码，不是原作者开源代码的链接。一定要细心！！】

11.推送本地的分支(XXX)到自己fork过的仓库中,2条命令. --> git fetch origin
和 git merge origin/XXX，【 如果这里的XXX分支 是 master，那么 git merge origin/master】。
【可以理解为：先去 origin 那里 把东西取回来，然后再在origin/master中 把自己local代码和自己forked的库代码合并。下一步就push到原作者账号上面去。】 【如果一开始有问题，可以多尝试编译几遍，可能是网络原因，有时候会无端出错。试多几次又可以了。前面后面的也通用】【可以通过git branch -a看看自己所在的本地分支是什么，如果没有origin的，就去掉origin，直接是XXX. 如下图，则为git merge poisson】

12.最后push自己的分支到自己fork过的仓库中. --> git push upstream XXX
or 【 如果这里的***分支 是 master，那么 git push upstream master】

13.在开源项目https://github.com/MessageKit/MessageKit.git的pull request中添加自己刚修改过的文件, 点"comment pull request"即可. 【如果在开源项目中找不到，可以试试在自己项目里找找看。查看branch是否发生改变，然后就会发现可以create pull request了。】

3. Q&A

1. 出现错误：git@github.com: Permission denied (publickey).
   –> 按照链接进行配置就好。https://www.jianshu.com/p/f22d02c7d943

2. 出现错误： git commit fatal: unable to auto-detect email address
   –> 参考：https://stackoverflow.com/questions/25671785/git-fatal-unable-to-auto-detect-email-address。也就是 $ git config --global user.email "you@example.com"
   把里面的邮箱 换成自己 GitHub账户的邮箱。

3. 错误：“Error connecting to agent: No such file or directory”
   –> 参考：https://unix.stackexchange.com/questions/464574/ssh-add-returns-with-error-connecting-to-agent-no-such-file-or-directory/464580

4. 错误：unable to start ssh-agent service, error :1058
   –> 参考：https://blog.csdn.net/qq_19926599/article/details/86380544。也就是 ，win+R打开services查看 “OpenSSH Authentication Agent” 服务是否开启，如果是 “disabled”（可能是win10自动更新给仅用了） 则将服务设为"Automatic"然后开启服务即可。

5. 错误：The authenticity of host ‘github.com (192.30.255.112)’ can’t be established
   –> 直接输入yes并回车就好了。参考 https://blog.csdn.net/Wbiokr/article/details/73431199.

6. 在第11 or 12步时，OpenSSL SSL_read: Connection was reset, errno 10054 或者 OpenSSL SSL_read: Connection was reset, errno 10054
   –> 可以多敲敲几次代码试试，这个错误的原因 似乎是网络不稳定。。。【把代理关掉】

7. 在用sphinx可视化doc文档的时候，需要安装一些包，如链接。这里需要注意：
   关掉fq代理。

8. “ERROR: Permission to git项目 denied to 某个用户user”, could not read from remote repository。
   引起这个错误的可能原因是 上面的具体步骤【10.】里，需要增加的remote upstream应该是自己账号里forked的项目，而不是原作者的开源项目。意思是： 需要在remote里先建立个自己账号的项目，合并好之后，再统一push到原作者的开源项目中。

9. rst 文件中需要输入公式？sphinx 语言，online documentation。
   可以参考文档 https://sphinx-rtd-trial.readthedocs.io/en/latest/ext/math.html

3. 其他

1.查看是否authentation: ssh -T git@github.com
2.查看有哪些remote：git remote -v
其他增加或删除remote的命令参考： https://www.cnblogs.com/cainiao-Shun666/p/15608573.html

Reference

[1] https://gist.github.com/zxhfighter/62847a087a2a8031fbdf