Issue（议题）：你可以在仓库中使用议题收集用户反馈，报告软件漏洞，并且组织要完成的任务。议题不只是一个报告软件漏洞的地方。

PR（Pull Request，拉取请求）：拉取请求可让你在 GitHub 上向他人告知你已经推送到仓库中分支的更改。在拉取请求打开后，你可以与协作者讨论并审查潜在更改，在更改合并到基本分支之前添加跟进提交。

如何使用 Issue 与 PR

Issue 与 PR 是 GitHub 上的两个重要功能，它们可以帮助你更好地管理项目。你应该在遇到下列情况下，去创建一个 Issue：

  • 报告你自己无法解决的错误
  • 讨论一个高级主题或想法(例如. 社区、远景、政策等)
  • 期望实现某新的特性，或者其它项目的想法

在 issue 的沟通中几点实用的技巧:

  • 如果你刚好看到一个开放的 issue，恰是你打算解决的， 添加评论，告诉他人你将负责这个。这样的话，可以避免他人重复劳动。
  • 如果说某个 issue 已经开放很久了， 这可能是已经有人正在解决中，又或者是早已经解决过了，所以也请添加评论，在打算开启工作之前，最好是确认一下。
  • 如果你创建了一个 issue，但是没多久自己解决了， 也要添加评论，让其他人知道，然后关闭该 issue。记录本身就是为社区的贡献。

而在下面的情形时，请你务必使用PR：

  • 提交补丁（例如，纠正拼写错误、损坏的链接、或者是其它较明显的错误）
  • 开始一项别人请求的任务，或者是过去在 issue 中早就讨论过的

如果说项目是托管在 GitHub 上的，以下是我们总结出的提交 PR 的建议：

  • Fork 代码仓库 并克隆到本地，在本地的仓库配置”上游”为远端仓库。这样你可以在提交你的 PR 时保持和”上游”同步，会减少很多解决冲突的时间。(更多关于同步的说明，请参考这里.)
  • 创建一个分支 用于自己编辑。
  • 参考任何相关的issue 或者在你的 PR 中支持文档(比如. “Closes #37.”)
  • 包含之前和之后的快照 如果你的改动是包含了不同的 HTML/CSS。在你的 PR 中加入相应的图片。
  • 测试你的改动！ 若测试用例存在的话，跑一遍，以覆盖你的更改，若没有的话，则创建相应的用例。无论测试是否存在，一定要确保你的改动不会破坏掉现有的项目。
  • 和项目现有的风格保持一致 尽你最大的努力，这也就是意味着在使用缩进、分号、以及注释很可能和你自己的风格大相径庭，但是为了节省维护者的精力，以及未来他人更好的理解和维护，还请你容忍一下。

感谢一切付出

与他人协作就是要相互尊重。你应该尊重你的贡献者们，耐心地回答他们的问题（即便问题看起来很简单），礼貌地对待建设性批评。

记住：对贡献者工作的感谢至关重要。如果某人只是创建了一个议题（即使这个议题没有经过深入研究，甚至没有重现），感谢他们。他们费力地把自己的椅子挪到离桌子近一点的地方，坐直身子，然后打了一点他们认为对你有用的东西，感谢他们。如果需要的话，用礼貌而又尊重的方式向他们询问更多的细节。

如果某人创建的 PR 没有满足你的高标准，感谢他们。感谢他们并礼貌地请求他们修改代码/编写测试/添加文档，等等。给他们一个你的 PR 的链接作为参考，或者给他们一个贡献指南的链接。

建设性地积极对话将会给予那些贡献者们额外的动力，让他们继续工作。

质量 vs 数量

最终，几乎总会有一个折衷。你可以决定不放低标准，哪怕是一点点也不行，很有可能你最终会自己完成所有的工作。或者，你可以决定放低对贡献者的标准（但是这可能会让你的标准显得毫无用处，因为它们没有被执行）。

我了解到，每个贡献者都需要使用不同的方法。这真的是由他们个人及其对贡献的兴趣决定的。

你应该考虑议题的紧急性、贡献者的经验、代码的复杂度、所需修复或功能的复杂度、贡献者的动机等因素。

通常，当议题非常重要时，我会礼貌地请求贡献者进行更改，然后等个几天，如果没有任何进展，我就会自己进行更改。至于那些没那么重要的（有了会更好）修复或者功能，我通常会把它们完全留给社区。

随着议题和 PR 数量的增长，跟踪、确定优先级并对它们进行分类就会成为一项艰巨的任务。这意味着标签会变得异常重要。

标签

GitHub 的标签是让 Issue 和 PR 保持优先级与组织性的好工具。虽然你可以通过标签进行搜索和过滤，但是我发现最有用的还是它可以帮助可视化项目的整体状态。

这样，你可以进入 Issue 页，看到大部分议题都被打上了 bug 标签（这意味着你应该停下来集中精力修复它们，而不是往前推进了）。 或者，你可以看见大部分 Issue 都被标记为 enhancement 或需要 features。priority 是另一个有用的标签，可以帮你首先关注到重要的东西。

此外，你的贡献者可以（也会）从你使用的标签中受益。例如，回到吸引贡献者，一些人可以进入 Issue 页，然后直观地地识别出那些需要社区帮忙处理的议题（help-wanted、pr-welcome，等等）。 除了职责单一的标签（比如 bug 或 enchancement）外，我推荐你使用标签来限定议题/PR 的范围。例如：

  • priority:low，priority:high
  • required:investigation，required:tests，required:docs 或者在单仓库的情况下： packages:package1，packages:package2 等等

标签让你可以快速地分辨出哪些问题是需要你（或你的贡献者）注意的，这些问题与哪个组件相关以及需要什么才能继续进行。

使用 Issue 和 PR 模板

利用 Issue 和 PR 模板，可以自定义和标准化你希望贡献者在你的仓库中打开议题和拉取请求时加入的信息。这将为你节省大量的时间，因为你不需要对每个问题或 PR 进行附加信息或更改的请求。有时候你还是需要这样做（因为有些贡献者根本不关注模板），但是它发生的频率要比不创建模板少得多。

你可以在 .github 文件夹中创建一个 ISSUE_TEMPLATE 文件夹，然后在其中创建一个 bug_report.md 文件和一个 feature_request.md 文件。这些文件将在用户打开 Issue 时显示给他们。

及时响应

如果贡献者在开源项目上打开了一个 Issue 或 PR，并且等了很长时间才收到回复，那么他们很可能会对它失去兴趣。如果你要花两周的时间响应一个需要你处理的 PR，而不是等待你要求的贡献者更改，那么你就会失去用户（即潜在的贡献者）。

所以帮你自己一个忙——及时响应。不一定要立马解决某人的问题，但是，即便是让用户知道你会在下周研究他们的议题，也给了他们一些确定性和时限。

坏消息是，你应该信守诺言。如果你的诺言有时没有完成，不要担心——我们所有人都有自己的生活，如果你因一些紧急的事情推迟了你在开源上的工作，是可以理解的。

如果发生了这种情况，就给一个简短的更新——又不是什么大事儿，只需要写一两个字，让人们知道他们一直在等待的那个功能被推迟了。