GitHub 引导开源项目启动指南

尝试这些技巧，更好地组织和管理 GitHub 上项目的进展。

图片来源：

Penguin, Boot。由 Opensource.com 修改。CC BY-SA 4.0。

使用 Git 管理项目，不仅仅是提交代码和处理分支。GitHub 驱动开发是一个流程，可以帮助您组织和管理 GitHub 上项目的进展，尽管其中大部分也适用于其他系统，例如 GitLab。这个概念不仅适用于开发人员；它也可以用于项目经理或任何参与项目开发的人员——甚至可以应用于非代码项目。

源代码控制是任何开发人员的关键技能，特别是那些在开源世界中工作的人（无论是作为工作的一部分还是作为爱好）。我的主要工作不是软件开发，但我会在工作中和工作之外大量涉足软件。我使用大量的开源工具，与开发人员和工程师团队合作，为其他人的项目做了大量的贡献（无论大小），甚至自己领导一些开源项目。我在管理像 GPIO Zero (一个用于 Raspberry Pi GPIO 的 Python 库) 这样的项目中了解到，明智地使用 GitHub 提供的工具是为项目指明方向的好方法。

虽然在命令行中使用 git 本身就是一项有用的技能，但大多数人只使用少数几个命令就能应付。如果您正在开发 Linux 内核，您可能需要了解更多高级 git，但如果您将个人项目放在 GitHub 上或为小型开源项目做贡献，您可能只需使用 clone、status、commit、pull 和 push 就能管理。一些额外的命令——如 diff、branch、checkout、stash、cherry-pick、tag 等——将会派上用场，并帮助您更进一步。

图片来源：

^{Ben Nuttall CC BY-SA}

使用 issue 作为开发路线图

您正在启动一个新项目。您决定使用 GitHub，创建一个仓库，并编写一个 README 文件，其中包含对项目的一句话描述。接下来呢？您想实现什么？为什么不在您的项目上发布一个 issue，并推动开发朝着解决该 issue 的方向发展呢？

GitHub issue 不仅仅供您的用户提交错误，它们也是您作为项目负责人为您的项目创建路线图的好方法。您可以从一些小的、容易实现的事情开始，也可以从您的主要功能开始。有些项目一开始就考虑得很宏大。Ubuntu 的 bug #1 是微软占据了市场的大部分份额，这是 Mark Shuttleworth 在 2004 年发布的。

发布一个关于您的项目在“功能完成”时将拥有的组件的概述可能是有意义的，并且关闭该 issue 将是您的一个重要里程碑。或者，您可以从一些较小的东西开始，比如您希望在公开发布之前看到的功能列表，对最小可行产品的描述，甚至只是您希望首先添加的单个功能。无论哪种方式最适合您的项目；完全取决于您。

在您自己的仓库上发布 issue 可以帮助为您的项目创建路线图，不仅为您和您的团队，也为您的用户和任何有兴趣为项目做贡献的人。有很多方法可以管理这一点（我将在下面的章节中介绍），但本质上，您只是将您对未来功能的愿望清单记录为 issue。当我为 GPIO Zero 想到一个想法时，我立即将其写成 GitHub issue (无论我认为它多么不寻常)。有时它会很快得到处理，由我或另一个团队成员处理。有时 issue 会长时间保持开放，但关于 issue 的讨论将推动决策。

图片来源：

^{Ben Nuttall CC BY-SA}

这种方法与测试驱动开发 (TDD) 类似，您首先编写一个测试，然后编写代码使测试通过。使用测试用例来驱动您的实现可能是实现您想要的 API 和功能的好方法，一次专注于一件事。一个示例 issue 可能是：“用户在登录时应该看到他们自己的仪表板。”

准确描述最终结果应该是什么样子是有用的，以便有一个具体的目标。在 GPIO Zero 中，我倾向于发布 issue，建议应该支持一种新设备。我详细说明设备包含什么以及它是如何工作的，然后我提出我希望看到的 API，并编写如果实现它就会工作的代码。这有助于开发人员（可能是也可能不是创建 issue 的同一个人）朝着预期的最终结果努力，并且能够通过展示我最初建议的代码现在可以工作来证明 issue 可以关闭。

使一切都成为对话

管理项目，特别是开源项目，最重要的事情之一是使一切都成为对话。如果您创建一个 issue，人们可以回复评论，赞同该 issue，提出建议和提出问题。您甚至可以用更多信息回复您自己的 issue，这使人们保持最新状态。即使您真的没什么可说的，GitHub 也允许您用快速点赞（或类似的东西）来回应评论。由此产生的对话既告知又记录决策过程，以便未来的贡献者和利益相关者可以收集关于项目状态的完整上下文。

图片来源：

^{Ben Nuttall CC BY-SA}

使用清单将 issue 分成多个部分

GitHub issue 允许（并鼓励）使用 Markdown 来格式化您的评论，甚至还有一个 WYSIWYG 工具栏，供不熟悉该语言的用户轻松格式化他们的回复。除了粗体、斜体等，您还可以轻松添加链接、编号和项目符号列表、代码块等等。您还可以使用清单；格式就像一个列表，每个项目旁边都有复选框。这些可以在 Markdown 中标记为“已选中”，也可以由任何对仓库具有推送权限的用户物理地选中和取消选中。这可能是将一个 issue 分成多个部分并将每个部分单独勾选掉的好方法。

图片来源：

^{Ben Nuttall CC BY-SA}

不要害怕提问

我学到的最重要的事情之一是不要害怕提出您不确定的问题或建议。GPIO Zero 最强大的功能之一来自于我（作为我自己项目上的 GitHub issue）提出的一个我认为很愚蠢的问题。我问：“是否有可能做到 X？” 在发布之前，我几乎放弃了这个 issue，因为我觉得问这个问题很愚蠢，并且认为我会从我的合著者那里得到一个直接的“不”。我最初确实得到了“不”，但后来他考虑了一下，并提出了一个解决方案，使我的建议成为可能，并且事实证明这对项目非常重要。

图片来源：

^{Ben Nuttall CC BY-SA}

另一方面，如果他说“不，那不可能”并关闭了 issue，那也不会是世界末日。不要害怕提出或建议您认为遥不可及的事情——您可能会有一天到达那里。您永远不知道您的问题会激发什么样的思考。如果您认为这是一个 issue，那么它就是一个 issue——即使它不能立即得到解决。

关闭 issue

如果您认为一个 issue 是不应该修复的，无论您看到什么原因——例如，它是一个误报的 bug，已经修复，或者您不愿意修复的东西（也许它超出了项目的范围）——您可以使用 issue 上的关闭按钮来关闭它。

或者，如果您提交了解决 issue 的内容，在 commit 消息中使用 issue 编号会做两件事：首先，它将 issue 编号（例如，“#1”）链接到 GitHub 上的 commit 消息，其次，如果您使用一个关键字，如 close 或 fix，后跟 issue 编号，例如

git commit -am "Add user dashboard, close issue #1"

那么 issue 会自动关闭。例如

图片来源：

^{Ben Nuttall CC BY-SA}

您可以在 pull request 中使用相同的约定。当创建一个 pull request 时，它会得到一个数字，就像 issue 一样（pull request 也是 issue）。如果您创建一个 pull request 来关闭一个 issue，只需在您的 pull request 标题中使用 close issue #1 格式。如果其他人创建了 pull request，您可以在合并之前编辑标题以添加此信息，issue 将自动关闭。或者，您始终可以单击 issue 上的关闭按钮。并且不要忘记，您始终可以重新打开已关闭的 issue。

使用标签对 issue 进行分类

将标签应用于您的 issue 有助于您、您的贡献者和任何浏览您项目的人查看每个 issue 的状态或他们如何参与。默认情况下，GitHub 为您提供六个颜色编码的标签，但您可以编辑或删除它们并添加其他标签。

您可能希望标记 issue 以说明哪些是 bug，哪些是功能请求，哪些正在进行中，哪些需要帮助，哪些是代码 issue，哪些是文档或测试 issue，等等。您甚至可以使用标签来显示每个 issue 的难度，以便贡献者可以轻松选择开始处理的内容。

图片来源：

^{Ben Nuttall CC BY-SA}

如果没有标签，贡献者可能会犯一个错误，即处理一个需要深入了解项目代码库的复杂 issue，而他们可能最好是处理一些更简单的东西。您可以应用标签，例如“正在进行中”标签，以确保新的贡献者不会开始处理另一个开发人员正在处理的 issue。您还可以将 issue 分配给您的团队成员，GitHub 允许您轻松查看分配给用户的所有 issue，这使得很容易看到每个人都在做什么。

编辑其他人的 issue

作为仓库的所有者或成员，您有权编辑其他人的 issue。明智地使用它，可以使您的项目受益。例如，用户经常粘贴未格式化的代码，这很难阅读，所以我将编辑评论以添加围栏代码块，使其对我自己和其他人来说可读。当您进行编辑时，请在回复中友好地指出您对用户的更改，以确保他们知道您编辑了什么以及原因。为您的贡献者提供技巧有助于他们避免将来出现类似的问题，并且（在示例案例中）确保他们不会认为 GitHub 会自动格式化他们粘贴的代码。

图片来源：

^{Ben Nuttall CC BY-SA}

GitHub 还允许您锁定 issue，因此如果有人反复回复已关闭的 issue 或具有辱骂性，您可以锁定该主题。

将 issue 分组到里程碑中

里程碑允许您将 issue 分组在一起，通常用于指定构成新版本甚至只是一个功能集所需的一组 issue。您可以创建一个里程碑，给它一个名称和（可选的）截止日期，并开始添加 issue。里程碑中所有 issue 的清单都会在每个 issue 关闭时自动勾选。issue 可以随时添加或删除，您可以更改截止日期。您将始终看到一个百分比，显示里程碑的完成进度。

考虑使用项目看板来管理工作流程

当您的 issue 积压开始增加时，有很多方法可以管理您的 issue 积压。GitHub 提供了一个名为项目看板的工具，允许您创建看板样式的 issue 看板，以识别它们的状态并管理工作流程。

还有一个名为 Waffle 的项目，允许您从您的 GitHub issue 创建类似的看板。Waffle 为人们添加 issue 提供了更简单的用户体验，并带有工具，可以自动在列之间移动 issue 卡片，您可以自定义这些列。

您可能会发现使用项目看板很有用，但它们并不适合所有人。不要觉得有义务尝试使用所有可用的工具——只需找到适合您和您的贡献者的工具即可。

处理 pull request

如果您幸运的话，您可能会收到来自社区成员的 pull request。您可能会发现这对您有帮助；也许用户决定在您的 issue 积压上做一些工作，或者他们已经识别并修复了一些 bug——太棒了！但是，并非每个 pull request 都会是这样。您可能会发现有人非常努力地工作并贡献了一些您只是不想要的东西，可能是因为它超出了您的项目范围，或者它使您的事情变得过于复杂。有些 pull request 只是没有帮助——例如，“我为您用 Go 重写了应用程序”的 pull request 不是您会急于合并的。

有些 pull request 将是混合的；也许他们添加了两个新功能——一个您想要，一个您不想要——并且取决于他们是如何做的，您可能能够找到一种方法来解决这个问题（查找 git cherry-pick）。但是，有时，如果不要求他们重新开始，就很难解决 pull request。如果是这种情况，请解释原因，表示感谢，并保持礼貌。尽量不要忽略他们，因为这可能会导致社区成员不满。即使您不打算立即处理贡献，也只需发送一个快速回复表示感谢。

图片来源：

^{Ben Nuttall CC BY-SA}

请记住，pull request 也是 issue，因此它们也有 issue 编号，您可以使用另一个 commit 关闭 pull request，也许这个 commit 解决了 pull request 试图解决的 issue（但以不同的方式）。您可以（虽然不必）通过使用“close”关键字引用两个 issue 编号来自动关闭 issue 和 pull request。例如，以下 commit 关闭 issue #123 和 pull request #124

git commit -am "Add user dashboard, close #123, close #124"

您还可以在 pull request 上提供反馈并要求用户进行更改，例如，如果您需要他们添加或删除功能、应用您自己的编码标准或基于您的 master 分支的最新版本进行 rebase。如果用户选中了 允许维护者编辑 框，那么您（或任何对您的项目具有推送权限的人）也可以将 commit 推送到此分支，这意味着您可以在合并之前自己应用这些更改。

当然，拒绝 pull request 是可以的，但最好始终解释原因，表示感谢，并尽量确保未来的贡献者不会浪费他们的时间。

发布贡献政策

为您的项目提供贡献政策很有用。这允许浏览您项目的用户了解您的指导原则是什么，您有什么期望，您希望人们如何与仓库互动，以及他们在打开 issue 或 pull request 之前是否应该做任何事情。

GitHub 提供了一种提供贡献政策的标准方法：编写您的指导原则并将其发布在您项目的根目录（或 .github 目录 中）中，文件名为 Contributing、CONTRIBUTING.md 或类似名称。当有人要去创建 issue 或 pull request 时，将显示指向您的政策的链接。

图片来源：

^{Ben Nuttall CC BY-SA}

提供开发者文档

优秀的文档使项目入门和取得进展变得更加容易。为您的用户提供文档并使其尽可能易于访问非常重要。不要假设他们像您一样技术——让人们容易上手并找出如何了解更多信息。边走边写文档，并保持更新。

图片来源：

^{Ben Nuttall CC BY-SA}

但是，文档不仅仅适用于用户。如果您曾经尝试为另一个项目做贡献，您可能在尝试设置以进行工作时遇到了障碍。如果您没有说明，您可能会运行 git clone 或尝试运行项目中的一些脚本并查看会发生什么——结果却发现很多缺失的依赖项和很多关于您已安装的内容、或者您对项目、或者它使用的工具以及它们如何协同工作的理解的假设。就像不提供用户文档是将潜在用户拒之门外的最简单方法一样，不提供开发者文档是将潜在贡献者拒之门外的最简单方法。

作为项目所有者，您应该考虑陌生人需要做什么才能使您的项目在本地运行，将更改应用于代码库，再次运行它，并看到更改生效。如果您不提供任何设置说明，或者您假设他们拥有您拥有的一切，并且知道您知道的一切，您可能会很快失去他们。

许多开发者对他们的用户做了太多的假设——Linux 用户假设其他人都在使用 Linux；Mac 用户假设每个人都在使用 Mac；Python 用户假设每个人都有 pip，理解 virtualenv 和一堆其他工具，等等。您需要提供一个完整的设置说明列表，该列表将尽可能多地适用于人们。您需要假设用户没有他们需要的所有工具，假设他们不了解您的代码库，假设他们不知道 pip 是什么——从头开始并帮助他们到达他们需要到达的地方才能开始 hack！尽量做到有帮助和全面，但不要居高临下。