Technical writer小白如何成为开源项目的贡献者？

想要参与到GitHub中的开源项目，我们需要明白整个贡献的流程是如何完成的。

整个流程实际上就是一个问题：如何能够修改GitHub网页中别人仓库中呈现出来的文档？

什么是仓库？

可以理解为一个仓库实际上就是一个项目，里面存放着所有和项目相关的文件，所有人都能够去浏览，纠错。我们所说的成为贡献者就是去为别人的仓库发现问题、解决问题。

以此次的pingcap的文档挑战赛为例子，pingcap是一个用户，docs就是一个仓库，里面就放着各种各样的文档，对应着他们的产品TIDB（一个数据库产品）。

作为technical writer，我们可以做的就是去查看仓库中一些文档，发现并解决问题，比如：

• 文档内容是否能够表意清晰
• 文档格式是否正确（是否符合markdown文件的格式要求）
• 文档是否能够正确引导别人使用TiDB（前提肯定是你要对这个产品十分了解）
• 将中文文档翻译为英文，将英文文档翻译为中文

如何对这个仓库中的文件进行修改？

有上游仓库、远程仓库、本地仓库三个概念需要先了解：

• GitHub上别人的原始仓库（“上游仓库”）
• GitHub上自己账号中的仓库（“远程仓库”）
• 自己电脑上的仓库（“本地仓库”）

这一个流程可以简单概括为：

1. fork仓库：在GitHub中将别人的“上游仓库”（pingcap的docs仓库），创建一个docs副本到你自己的账号中作为“远程仓库”；
2. clone仓库：然后将你自己的这个“远程仓库”，下载到本地来作为“本地仓库”，所有修改都是在自己电脑上进行本地修改；
3. 修改文件：你能够在你的电脑上进行修改了；
4. 提交文件：将你做出的本地修改同步上传到GitHub上的远程仓库（即“push”），此时本地仓库就和你远程仓库已经同步为一模一样了；
5. 请求修改：然后请求将远程仓库中做出的修改上传到pingcap的上游仓库中去，等待审核。

各个仓库间的关系

远程仓库到上游仓库之间，是为了能够让不同的人进行协同操作，各个贡献者都会将上游仓库fork到自己的账号中作为远程仓库，所有的修改都通过提交请求从远程仓库传到上游仓库，保证了不同贡献者之间的协同工作，也方便上游仓库审核者管理。

本地仓库到远程仓库之间，是为了能够进行版本控制。每做完一次本地修改，都上传到远程仓库，每次上传一次，就是一个新的版本，所有的上传历史都记录在远程仓库中，如果想要回退到某个版本，就很容易，以便于进行版本控制。

这大概就是整个修改的流程了，但是在各个环节还有很多细节需要讲解，但是只要你明白了这整个提交流程的逻辑，那你理解和操作起来就会十分顺手。接下来我们就来看看，具体的操作流程是怎么样的。

第一步：fork上游的docs仓库

进入目标仓库页面，点击右上角的fork，即可fork到自己的存储库中，作为远程仓库，也是个人副本。

此处需要强调的是：

• 当认领了中文仓库 pingcap/docs-cn的一个待翻译 PR 后，你需要在英文仓库 pingcap/docs 建一个对应的英文 PR。
• 当认领了英文仓库 pingcap/docs 的一个待翻译 PR 后，你需要在中文仓库 pingcap/docs-cn 建一个对应的中文 PR。

第二步：克隆docs远程仓库

1. 点击最右上角的头像，点击Your repositories进入自己的个人存储库，里面有所有的仓库，找到刚刚fork的那个仓库，点击进入。

   

2. 点击绿色的code按钮，可以看到有三种不同的方式进行克隆

• 一是通过链接

• 二是通过GitHub Desktop打开

• 三是通过下载安装包打开

  

3.这里我们点击 Open with GitHub Desktop 打开，网页就会显示出请求打开GitHub Desktop的请求，点击允许

查看这个文档安装 GitHub Desktop。

安装很简单，不需要配置什么，安装路径都不需要选择，下载完之后点击安装就完事了。安装好了之后，在登陆好就行了。

4.可以看到在GitHub Desktop中就会弹出克隆这个仓库的请求，这里需要记住你克隆的地址，因为后续需要都对本地文件做出修改。

第三步：在本地仓库中修改文件

3.1确保本地仓库和上游保持一致

1.在每次开始工作前，要查看本地的master分支是否与上游的master分支同步，需要将上游master分支的变化merge到本地来（merge也就是合并的意思）。

分支这个概念我 们在下一步骤会讲到，你可以理解为不同的分支，就是不同的仓库版本，master就是最主要的分支。

这一步的目的，是保证你电脑上本地的这个仓库的master分支能够和pingcap上游仓库的上游master分支保持同步，毕竟人家那个仓库是时时刻刻在变化的，而你本地上的那个不是。如果不同步的话，最终请求的时候会起冲突。

同时，也不一定是merge上游的master分支，但是此次文档挑战赛，我们翻译的大多数文档都是基于master分支，也就是最新的版本。但也有一些文档是基于比如7.1版本。

• 点击上方窗口顶端的 Branch→Merge into Current Branch

• 在弹出的搜索框中搜索 master

• 选中下方的 upstream/master

• 然后点击 Create a merge commit按钮。

  

这里有两种情况，一种是上游未发生改变，一种是上游发生改变：

• 未改变：其实我们刚刚才进行了fork，clone的操作，这么短的时间上游是不会有什么改变的，所以你会发现，在选择 upstream/master 后，界面底部会有当前 master branch 已为最新的提示。而且，Create a merge commit 会呈现浅蓝色，无法点击。

• 上游有改变：比如你早上clone好了仓库，但是中间有事外出，晚上再来继续，这一段时间间隔中，上游仓库就可能发生了改变，此时这个按钮就是可以点击的，你就需要进行Create a merge commit这一操作了。

  这一步意味着，你把上游仓库master分支的的变化，merge融合到了你本地仓库里的master分支，直接跳过了你GitHub上的那一个仓库，所以，你还需要进行push origin这一步，把你本地的修改，推到你GitHub仓库里中去。

2.点击 Push origin，将刚刚 merge 到本地 master分支的变化推送到GitHub上的远程仓库docs，这样一操作完，pincap上游仓库的master分支，电脑上本地仓库的master分支，和GitHub上远程仓库的master分支，就都同步了。

3.2 创建分支

1.通过点击上方工具栏中的Current Branch新建分支，来开始修改文件。新建分支的名称，应当是对自己的修改进行一个简单总结。

branch，也叫做分支，类似一个个不同的仓库版本。创建新的分支时，会询问你是基于哪个现有分支创建的，一般你修改的文件或翻译的文档是哪个分支就基于哪个分支创建新分支。在这个新的中进行具体的修改，是为了方便管理，这样无论我们如何修改都不会影响到原来的分支。

最终我们提交到pingcap/docs仓库的，就是将这一整个分支都提交过去。你会看到这个仓库里本来就有很多分支，这些就是其他贡献者为了贡献自己的修改而创建的。

如果你的贡献有价值，那么最终审核者就会将你创建的分支merge到pingcap/docs那个仓库的分支中去，就成功贡献了。

2.点击新建之后，会弹出你这个分支是基于那个分支的，一般我们都是基于master的。

3.新建分支成功后，可以看到上方的Current Branch已经切换到了新建的分支。

3.点击下方的Open the repository in your external editor，在自己的本地编辑器中进行编辑修改。

这里我推荐的编辑器是visual studio code，下载教程请看

第四步：提交文件

这后面的几张图我不小心换成了docs-cn仓库，你们的操作中应该还是docs仓库

在进行这一步之前，我们用术语来了解一下之前说的那个流程。

commit，publish，create pull request 这三个东西。理解之后，你就大致能够明白整个流程关系了。

• commit：将你自己在新建分支中做的那些修改先缓存在电脑里，也就是说你每次修改完之后，就点击commit，然后添加以下description来描述你修改了什么，先缓存着，方便下次接着修改。（此时修改还在你自己电脑上）
• publish：将缓存的这个分支提交到你自己GitHub上的远程仓库。（此时修改同步到了你的GitHub上了）
• create pull request：提交了新的分支到远程仓库后，就会提醒你可以create pull request，通过这一步发起请求，让pingcap那边的reviewer来审查，看你的这个分支中的修改是否有价值。如果有，那么你的pull request就会被合并。（此时修改请求已经提交给pingcap的docs仓库，等待审核即可。）

1.在你打开本地编辑器后，只要你做出了任何修改，回到GitHub Desktop中来，会自动显示你进行了哪些修改，红色就是删除了哪些东西，绿色就是增加的哪些东西。

2.点击左下方的commit进行提交，在点击提交之前，需要在commit按钮上方的Summary中简单总结自己的修改，就像之前创建分支时，新建分支名一样。

如果你要离开这个分支，那你就要先将commit提交到缓存中去，防止丢失掉你修改的内容。

3.然后点击上方工具栏第三个按钮Publish branch将新建的分支和和你在这个分支上的修改，提交的Commit都同步到你GitHub的那个docs仓库中去。

4.然后点击界面上的preview pull request，预览一下你修改的文件，再次确认是否正确

5.你会看到以下界面，然后点击Create Pull Request按钮请求上游仓库拉取。

6.然后就会自动跳转到网页端pingcap/docs仓库的提交pull request界面，仓库的管理员已经预设了一个模板，你按照要求填好就行了，主要是确认你是否已经签订了协议，修改了哪些地方，以及修改的是哪个版本。

然后等待审核就行了。