6.2 GitHub - 为项目贡献

Tony 正在为他的 Arduino 可编程微控制器寻找代码，并在 GitHub 上找到了一个很棒的程序文件：https://github.com/schacon/blink。

唯一的问题是闪烁速率太快了。我们认为在每次状态更改之间等待 3 秒而不是 1 秒会好得多。所以，让我们改进程序，并将其作为建议的更改提交回项目。

首先，我们点击前面提到的“Fork”按钮，获取我们自己的项目副本。这里我们的用户名是“tonychacon”，所以这个项目的副本位于 https://github.com/tonychacon/blink，我们可以在那里进行编辑。我们将在本地克隆它，创建一个主题分支，进行代码更改，最后将更改推送到 GitHub。

现在，如果我们回到 GitHub 上的派生，我们会看到 GitHub 注意到我们推送了一个新的主题分支，并为我们提供了一个大大的绿色按钮，用于查看我们的更改并向原始项目打开拉取请求（Pull Request）。

您也可以前往 https://github.com/<user>/<project>/branches 的“Branches”（分支）页面，找到您的分支并从那里打开新的拉取请求。

如果我们点击那个绿色按钮，我们会看到一个屏幕，要求我们为拉取请求提供标题和描述。这几乎总是值得付出一些努力的，因为好的描述有助于原始项目的所有者确定您想要做什么，您的提议更改是否正确，以及接受这些更改是否会改进原始项目。

我们还会看到主题分支中“领先”于 master 分支的提交列表（本例中只有一个），以及如果此分支被项目所有者合并，将进行的所有更改的统一差异（diff）。

当您在此屏幕上点击“Create pull request”（创建拉取请求）按钮时，您所派生项目的所有者将收到有人建议更改的通知，并会链接到一个包含所有这些信息的页面。

此时，项目所有者可以查看建议的更改并进行合并、拒绝或评论。假设他喜欢这个想法，但希望灯灭的时间比亮的时间稍长一些。

在分布式 Git 中介绍的工作流程中，这种对话可能通过电子邮件进行，但在 GitHub 上，这发生在在线。项目所有者可以查看统一差异（unified diff）并通过点击任意行来留下评论。

一旦维护者发表此评论，打开拉取请求的人（以及任何关注该仓库的人）都将收到通知。我们稍后将介绍如何自定义此功能，但如果 Tony 开启了电子邮件通知，他将收到这样的电子邮件：

任何人都可以对拉取请求留下一般性评论。在拉取请求讨论页面中，我们可以看到一个项目所有者既对一行代码进行评论，又在讨论区留下一般性评论的例子。您可以看到代码评论也被带入到对话中。

现在贡献者可以看到他们需要做什么才能使他们的更改被接受。幸运的是，这非常简单。通过电子邮件，您可能需要重新打包您的系列并重新提交到邮件列表，而在 GitHub 上，您只需再次提交到主题分支并推送，这将自动更新拉取请求。在拉取请求最终页面中，您还可以看到旧的代码评论在更新后的拉取请求中已被折叠，因为它是在已更改的行上进行的。

向现有拉取请求添加提交不会触发通知，因此一旦 Tony 推送了他的更正，他决定留下评论，告知项目所有者他已进行了请求的更改。

一个有趣的地方是，如果您点击此拉取请求的“Files Changed”（文件更改）选项卡，您将获得“统一”差异（unified diff）——也就是说，如果此主题分支被合并，将引入到您的主分支的总聚合差异。用 git diff 的术语来说，它基本上会自动显示该拉取请求所基于的分支的 git diff master…​<branch>。有关此类差异的更多信息，请参阅确定引入了什么。

您还会注意到的另一件事是，GitHub 会检查拉取请求是否可以干净地合并，并提供一个按钮让您在服务器上执行合并。此按钮仅在您对仓库具有写入权限且可以进行简单合并时才会显示。如果您点击它，GitHub 将执行“非快进式”（non-fast-forward）合并，这意味着即使合并可以是快进式的，它仍然会创建一个合并提交（merge commit）。

如果您愿意，您可以简单地将该分支拉取下来并在本地合并。如果您将此分支合并到 master 分支并推送到 GitHub，拉取请求将自动关闭。

这是大多数 GitHub 项目使用的基本工作流程。创建主题分支，在其上打开拉取请求，随后进行讨论，可能在该分支上进行更多工作，最终请求被关闭或合并。

重要的是要理解，许多项目并不真正将拉取请求视为应该按顺序干净应用的完美补丁队列，而大多数基于邮件列表的项目则将补丁系列贡献视为如此。大多数 GitHub 项目将拉取请求分支视为围绕提议更改的迭代对话，最终通过合并应用一个统一的差异（diff）。

这是一个重要的区别，因为通常在代码被认为是完美之前就提出了更改建议，这在基于邮件列表的补丁系列贡献中更为罕见。这使得可以与维护者进行更早的对话，从而使找到正确解决方案成为一项社区努力。当通过拉取请求提出代码并且维护者或社区建议更改时，补丁系列通常不会重新生成，而是将差异作为新的提交推送到分支，在保留先前工作上下文的情况下推进对话。

例如，如果您再次查看最终拉取请求，您会注意到贡献者没有重定基他的提交并发送另一个拉取请求。相反，他们添加了新的提交并推送到现有分支。这样，如果您将来回溯查看此拉取请求，您可以轻松找到所有关于决策原因的上下文信息。网站上的“合并”按钮特意创建了一个引用拉取请求的合并提交，以便在必要时方便回溯和研究原始对话。

如果您的拉取请求过期或无法干净地合并，您需要修复它，以便维护者可以轻松合并。GitHub 会为您测试并告知您每个拉取请求的底部，合并是否简单。

如果您看到类似拉取请求无法干净合并的情况，您会希望修复您的分支，使其变为绿色，这样维护者就无需额外工作了。

您有两种主要的选择来完成此操作。您可以将您的分支重定基到目标分支之上（通常是您派生仓库的 master 分支），或者您可以将目标分支合并到您的分支中。

GitHub 上的大多数开发者会选择后者，原因与我们上一节中讨论的相同。重要的是历史和最终合并，所以重定基除了能带来稍微干净一些的历史外，并没有太大的好处，而且它远比合并更困难、更容易出错。

如果您想合并目标分支以使您的拉取请求可合并，您需要将原始仓库添加为新的远程仓库，从中抓取（fetch），将该仓库的主分支合并到您的主题分支中，修复所有问题，最后将其推送回您打开拉取请求的同一个分支。

例如，假设在我们之前使用的“tonychacon”示例中，原作者做了一个会在拉取请求中产生冲突的更改。让我们过一遍这些步骤。

完成这些操作后，拉取请求将自动更新并重新检查是否可以干净地合并。

Git 的一个优点是您可以持续地进行此操作。如果您的项目运行时间很长，您可以轻松地一次又一次地从目标分支合并，并且只需要处理自上次合并以来出现的冲突，这使得整个过程非常易于管理。

如果您确实希望重定基分支以清理它，当然可以这样做，但强烈建议不要强制推送到已经打开拉取请求的分支。如果其他人已经拉取并在此分支上进行了更多工作，您将遇到重定基的风险中概述的所有问题。相反，将重定基后的分支推送到 GitHub 上的一个新分支，并打开一个新的拉取请求，引用旧的拉取请求，然后关闭原始的。

您的下一个问题可能是“我如何引用旧的拉取请求？”。事实证明，在 GitHub 中，您几乎可以在任何可写入的地方，以多种方式引用其他内容。

让我们从如何交叉引用另一个拉取请求或议题（Issue）开始。所有拉取请求和议题都被分配了编号，并且在项目内是唯一的。例如，您不能同时拥有拉取请求 #3 和议题 #3。如果您想从任何其他拉取请求或议题中引用某个拉取请求或议题，您只需在任何评论或描述中放入 #<num>。如果议题或拉取请求位于其他地方，您也可以更具体；如果您引用的是您所在仓库派生中的议题或拉取请求，请写入 username#<num>，或使用 username/repo#<num> 来引用另一个仓库中的内容。

让我们看一个例子。假设我们在前面的例子中重定基了分支，为其创建了一个新的拉取请求，现在我们想在新拉取请求中引用旧的拉取请求。我们还想引用仓库派生中的一个议题以及一个完全不同项目中的议题。我们可以像拉取请求中的交叉引用那样填写描述。

当我们提交此拉取请求时，我们将看到所有内容呈现，如同拉取请求中渲染的交叉引用。

请注意，我们放入的完整 GitHub URL 被缩短为仅显示所需的信息。

现在，如果 Tony 返回并关闭原始拉取请求，我们会看到通过在新拉取请求中提及它，GitHub 已自动在拉取请求时间线中创建了一个回溯事件。这意味着任何访问此拉取请求并看到它已关闭的人都可以轻松链接回替代它的那个。该链接将看起来像在已关闭的拉取请求时间线中链接回新的拉取请求。

除了议题编号，您还可以通过 SHA-1 引用特定的提交。您必须指定完整的 40 个字符的 SHA-1，但如果 GitHub 在评论中看到它，它将直接链接到该提交。同样，您可以像引用议题一样，在派生或其他仓库中引用提交。

第一个真正有用的 GitHub 特有 Markdown 功能，尤其适用于拉取请求，是任务列表。任务列表是您想要完成的待办事项的复选框列表。将其放入议题或拉取请求中通常表示在您认为项目完成之前需要完成的事项。

您可以创建这样的任务列表：

如果我们将此包含在我们的拉取请求或议题的描述中，我们将看到它呈现为Markdown 评论中渲染的任务列表。

这经常用于拉取请求中，以指示在拉取请求准备好合并之前，您希望在该分支上完成的所有工作。真正酷的部分是，您可以简单地点击复选框来更新评论——您无需直接编辑 Markdown 来勾选任务。

更重要的是，GitHub 会在您的议题和拉取请求中查找任务列表，并在列出它们的页面上将其显示为元数据。例如，如果您有一个包含任务的拉取请求，并且您查看所有拉取请求的概览页面，您可以看到它完成了多少。这有助于人们将拉取请求分解为子任务，并帮助其他人跟踪分支的进度。您可以在拉取请求列表中的任务列表摘要中看到一个示例。

当您尽早打开拉取请求并将其用于跟踪功能实现进度时，这些功能非常有用。

您还可以在评论中添加代码片段。如果您想在实际作为提交在分支上实现之前，展示您可以尝试做的事情，这尤其有用。这通常也用于添加不工作的示例代码，或者此拉取请求可以实现什么。

要添加代码片段，您必须用反引号将其“围起来”。

如果您像我们那样添加语言名称（例如 'java'），GitHub 也会尝试对片段进行语法高亮。在上面的示例中，它最终会呈现为渲染后的围栏代码示例。

如果您正在回复长评论的一小部分，可以通过在行前加上 > 字符来选择性地引用其他评论中的内容。事实上，这非常常见且有用，以至于有一个键盘快捷键。如果您高亮显示评论中要直接回复的文本并按下 r 键，它将自动为您在评论框中引用该文本。

引用内容看起来像这样：

渲染后，评论将显示为渲染后的引用示例。

最后，您还可以在评论中使用表情符号。这实际上在许多 GitHub 议题和拉取请求的评论中被广泛使用。GitHub 中甚至有一个表情符号助手。如果您正在输入评论并以 : 字符开头，自动完成器将帮助您找到您想要的内容。

表情符号在评论中的任何地方都以 :<名称>: 的形式出现。例如，您可以这样写：

渲染后，它看起来会像大量使用表情符号的评论。

这不是说它非常有用，但它确实为原本难以表达情感的媒介增添了趣味性和情感元素。

这在技术上并非 GitHub 风味 Markdown，但它非常有用。除了在评论中添加 Markdown 图片链接（这可能难以找到和嵌入 URL）之外，GitHub 还允许您将图片拖放到文本区域中以进行嵌入。

如果您查看拖放图片以上传并自动嵌入它们，您会看到文本区域上方有一个小小的“Parsed as Markdown”（解析为 Markdown）提示。点击它将为您提供一个完整的 GitHub Markdown 功能备忘单。