创建GitHub Pull Request的简单指南

作为像Perfect这样的免费开源软件项目，最大的挑战是如何在保持质量和凝聚力的同时，使社区参与。 作为项目“核心”团队的成员，我们经常离代码很近，看不到极端情况，也没有考虑到我们尚未遇到的情况-在这里使用库的人会遇到问题，错误，或优化机会对于​​项目的成熟至关重要。

幸运的是，git（在我们的特定情况下为GitHub）使用称为“请求”的流程使社区贡献变得容易。

“我很乐意为此做一个请求请求，但我不知道该怎么做”

在我们关于开放社区Slack组的日常讨论中，当被告知有关文档或代码更改的需求时，有人多次评论“我很乐意为此提出请求，但我不知道该怎么做”。 。

好吧，如果您曾经说过或曾经想过并且犹豫要为FOSS项目做出贡献，请继续阅读！

什么是“拉取请求”

“拉取请求”这个术语有点奇怪，除了可能有“补丁”的概念外，它与git社区以外的任何事物都不能很好地等同。

实际上，拉取请求（也称为PR）是您提交代码更改同时促进公开对话和审阅的一种方法。

PR的简单解释是：

• 您可以修改自己的git存储库副本
• 一旦感到满意， 就会触发一个请求，将您的更改合并到原始存储库中，并说明您的操作以及原因
• 然后，项目管理员会查看您的更改并接受更改 ，或者就更改进行讨论。

实际中的拉取请求

为了逐步演示您作为读者的身份如何进行PR，我将描述对Perfect Documentation资源库进行PR的过程。

Perfect项目的整个文档集都是开源的，我们会定期更新主站点上的HTML版本-从GitHub存储库的Markdown文件生成。 这意味着，如果发现拼写错误或可以做出的改进，那么您将有能力提供帮助！

因此，我今天注意到CouchDB驱动程序文档中提到的版本不正确：它引用的majorVersion为0，应为1。

回到源代码的GitHub回购页面https://github.com/PerfectlySoft/PerfectDocs/blob/master/guide/CouchDB.md，我可以看到它也已经过时了，因此需要更改。

第一步，“分叉”存储库。

哇，更多git术语：“ fork”是在特定时间点故意创建的版本库。 想象一下，如果您沿着森林步道走，突然之间的路径被分成两部分，这就是“叉子”。 一个路径可能会继续到达预期的目的地，而另一条路径可能会将您带向完全不同的方向……有时会合并回到原始路径中。

“叉子”是在特定时间点故意创建的版本库的新版本。

要创建Perfect文档存储库的分支，请使用GitHub页面右上方的“ Fork”按钮。

然后，您会看到一个对话框，询问您要将新叉子放置在何处。 选择一个位置：您的列表可能比我的列表更短或更长时间……

现在我们有了自己的fork，可以编辑文件了。

编辑并提交更改

对于我们将要进行的小更改，GitHub用户界面使操作变得简单。 对于更广泛的更改（尤其是涉及代码），建议将新的存储库克隆到本地环境，并在提交之前使用Xcode之类的IDE来编辑和测试代码。

看到此演示正在更改文档的一小部分，我将直接在GitHub UI中进行编辑。

在页面上以自己的仓库查看文件时，您会看到一个铅笔图标，用于进入编辑模式：

单击此按钮将使您进入编辑模式。 滚动到要更改的位置-在我的情况下，我想将“ 0”更新为“ 1”。

完成更改后，向下滚动至页面的“提交消息”部分，然后输入有关更改内容的简短说明：

现在，此更改仍在您的文档存储库副本（分叉）上，因此下一步是将路径重新组合在一起。

提交您的拉取请求

当查看分叉存储库的“根”（也显示自述文件的根）时，您将看到一个标有“新请求请求”的按钮。 单击此按钮将带您进入一个页面，该页面专门向您显示您的版本与父版本之间的所有差异。 它还会通知您是否存在任何妨碍成功的合并冲突。

单击绿色的大按钮“创建请求”，然后您可以借此机会总结在PR中所做的所有更改。

现在单击“创建请求请求”将在父资源库中向您显示可公开查看的PR条目。 请注意，有一个橙色的“ CLA助手”注释，以及一条消息“某些检查尚未完成”……

该“ CLA”是“贡献者许可协议”，用于清理所有许可问题的分配。 如果您想阅读有关CLA流程的更多信息，请查看有关CLA的Wikipedia文章，并阅读Perfect的CLA。

单击该按钮将带您进入一个您可以同意条款的页面，这是许多FOSS项目接受PR所必需的。 底部是“使用GitHub登录以同意”按钮。 单击此按钮将带您返回PR审阅页面，现在所有内容均为绿色！

提交拉取请求后会发生什么？

好问题！ 在理想的世界中，我们当中的一个人会迅速看到并采取行动评估PR。 但是，由于日程安排多变，电子邮件垃圾邮件过滤器和生活普遍繁忙，我们可能会错过通知。 让我们知道的100％最佳方法是在Perfect Slack频道上弹出，并通过提及自己（@iamjono）或Kyle（@kylej）在#general（或#docs）中知道。

然后，我们将处理或委派更改的审查。