github开源项目_使用GitHub引导您的开源项目的指南-白红宇

github开源项目_使用GitHub引导您的开源项目的指南

阅读量：2524 次

发布时间：2019-05-11

本文共 5632 字，大约阅读时间需要 18 分钟。

github开源项目

除了提交代码和使用分支机构之外，使用git管理项目还有很多。 GitHub驱动的开发是一个过程，可以帮助您组织和管理GitHub上项目的进度，尽管其中很多也可以应用于其他系统，如。这个概念不仅适用于开发人员。它可以用于项目经理或参与项目开发的任何人，甚至可以应用于非代码项目。

对于任何开发人员，尤其是在开源世界中工作的人员（无论是作为工作的一部分还是业余爱好），源代码控制都是一项关键技能。我的主要工作不是软件开发，但是我沉迷于软件的上班和下班。我使用大量开源工具，与开发人员和工程师团队合作，为其他人的项目做出了各种贡献（无论大小），甚至我自己也领导了几个开源项目。我在管理诸如（，的Python库）之类的项目时学到的很多东西是，聪明地使用提供的工具可以为指导项目提供一个很好的方法。

虽然在命令行上使用git本身是一项有用的技能，但大多数人仅需执行少量命令。如果您使用的是，则可能需要了解一些更高级的git，但是如果要将个人项目保留在GitHub上或为一个小型开源项目做贡献，则可能需要使用clone进行管理。，状态，提交，拉动和推动。一些额外的命令（如diff ， branch ， checkout ， stash ， cherry-pick ， tag等）将派上用场，并帮助您进一步发展。

^{本·努塔尔（Ben Nuttall）}

将问题用作发展路线图

因此，您正在开始一个新项目。您决定使用GitHub，创建存储库并编写自述文件，其中包含有关项目内容的单行描述。接下来是什么？您想达到什么目的？为什么不在您的项目上发布问题并推动开发以解决该问题呢？

GitHub问题不仅是您的用户提交错误，还是作为项目负责人为您创建项目路线图的好方法。您可以从一些小巧且可快速实现的事情开始，也可以从主要功能开始。一些项目从大胆入手。 Ubuntu的错误＃1是，这是Mark Shuttleworth在2004年发布的。

发布项目“功能已完成”时将拥有的组件概述可能是有意义的，而结束该问题对您而言将是一个巨大的里程碑。或者，您可以从较小的内容开始，例如您希望在公开发布之前看到的功能列表，对最低限度可行的产品的描述，甚至只是您希望首先添加的单个功能。无论哪种方式最适合您的项目；这完全取决于您。

将问题发布到您自己的存储库中不仅可以为您和您的团队，还可以为您的用户以及对项目做出贡献的任何人，为您的项目创建路线图。有很多方法可以解决此问题（我将在以下各节中进行介绍），但是从本质上讲，您只是在记录将来功能的愿望清单。当我想到GPIO零的想法时，我立即将其写为GitHub问题（）。有时，我或其他团队成员会很快处理它。有时，这个问题会持续很长时间，但是有关该问题的讨论将推动决策。

^{本·努塔尔（Ben Nuttall）}

这种方法与（TDD）并无不同，您首先编写一个测试，然后编写代码以使测试通过。使用测试用例来驱动您的实现可能是一次实现您想要的API和功能的好方法，一次只关注一件事。一个示例问题可能是：“用户登录时应该看到自己的仪表板。”

准确描述最终结果应该是有用的，以便有一些特定的目标。在GPIO零中，我倾向于发布一些问题，建议应支持新设备。我详细介绍了该设备包含的内容及其工作方式，然后提出了一个API，我希望该API能够看到并编写能够实现的代码。这有助于开发人员（创建问题的人可能不同，也可能不是同一人）朝着预期的最终结果努力，并能够通过显示我最初建议的代码现在可以工作来证明问题可以解决。

让一切成为对话

管理项目（尤其是开放源代码项目）最重要的事情之一就是使所有内容都成为对话。如果您创建了问题，则人们可以回复并提供评论，以批准问题，提出建议和提出问题。您甚至可以提供更多信息来回复自己的问题，以使人们保持最新状态。即使您实际上没有话要说，GitHub也可以让您快速赞一下（或类似的）评论。最终的对话既可以为决策提供依据，也可以为决策提供文档，以便将来的参与者和利益相关者可以收集有关项目状态的完整信息。

^{本·努塔尔（Ben Nuttall）}

使用清单将问题分成几部分

GitHub问题允许（并鼓励）使用格式化您的注释，甚至还有一个WYSIWYG工具栏，供不熟悉该语言的用户轻松格式化其答复。除粗体，斜体等外，您还可以轻松添加链接，编号和项目符号列表，代码块等。您也可以使用清单。格式就像一个列表，其中每个项目都有复选框。这些可以在Markdown中标记为“已选中”，也可以由对存储库具有推送权限的任何用户进行物理检查和不检查。这是将问题分成多个部分并分别进行检查的一种好方法。

^{本·努塔尔（Ben Nuttall）}

不要害怕问

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

^{本·努塔尔（Ben Nuttall）}

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

结束问题

如果您认为某个问题出于某种原因不应该得到解决，例如，它是错误报告的错误，已经得到解决，或者是您不愿意解决的问题（也许超出范围）项目）），您可以使用问题上的“ 关闭”按钮将其关闭。

或者，如果您提交可解决问题的内容，则在提交消息中使用问题编号有两件事：第一，它将问题编号（例如“＃1”）链接到GitHub上的提交消息，第二，如果您使用诸如close或fix之类的后跟发行号，例如：

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

然后问题将自动关闭。例如：

^{本·努塔尔（Ben Nuttall）}

您可以在拉取请求中使用相同的约定。创建拉取请求时，它会像问题一样获得一个数字（拉出请求也是问题）。如果您提出关闭问题的请求请求，只需在请求请求标题中使用关闭问题＃1格式。如果其他人提出了拉取请求，则可以编辑标题以在合并之前添加此信息，并且此问题将自动关闭。或者，您始终可以在问题上单击“ 关闭”按钮。并且不要忘了，一旦问题关闭，您可以随时重新打开它。

分类标签问题

在您的问题上加上标签可以帮助您，您的贡献者以及浏览您的项目的任何人看到每个问题的状态或他们如何参与。默认情况下，GitHub为您提供六个颜色编码的标签，但是您可以编辑或删除它们并添加其他标签。

您可能需要标记问题，以说出哪些是Bug，哪些是功能请求，哪些正在进行中，哪些需要帮助，哪些是代码问题，哪些是文档或测试问题，等等。您甚至可以使用标签显示每个问题的难度，以使贡献者可以轻松地选择要开始的工作。

^{本·努塔尔（Ben Nuttall）}

没有标签，贡献者可能会犯错误，以解决一个复杂的问题，需要对项目的代码库有深入的了解，而他们可能会更好地进行一些简单的事情。您可以应用标签，例如“进行中”标签，以确保新的参与者不会开始处理其他开发人员正在处理的问题。您还可以将问题分配给团队成员，并且GitHub允许您轻松查看分配给用户的所有问题，从而轻松查看每个人的工作情况。

编辑其他人的问题

作为存储库的所有者或成员，您有权编辑其他人的问题。明智地使用它可以使您的项目受益。例如，用户经常粘贴未格式化的代码，这很难阅读，因此我将编辑注释以添加受保护的代码块，以使其对我自己和其他人可读。进行编辑时，请在回复中向用户指出您的更改，以确保他们知道您编辑的内容以及原因。向您的贡献者提供提示可帮助他们避免将来出现类似问题，并且（在示例中）确保他们不会假设GitHub自动格式化其粘贴的代码。

^{本·努塔尔（Ben Nuttall）}

GitHub还允许您锁定问题，因此，如果有人反复回答已解决的问题或被滥用，则可以锁定该线程。

将问题分组为里程碑

里程碑使您可以将问题分组在一起，通常可以指定构成新版本甚至只是功能集所需的一组问题。您可以创建一个里程碑，为其命名并提供（可选）截止日期，然后开始添加问题。在关闭每个问题后，会自动检查里程碑中所有问题的清单。您可以随时添加或删除问题，也可以更改截止日期。您将始终看到一个百分比，显示完成里程碑的进度。

考虑项目委员会来管理工作流程

当问题积压开始累积时，有许多方法可以对其进行管理。 GitHub提供了一个称为的工具，该工具可让您创建问题的式板以识别其状态并管理工作流程。

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

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

处理请求请求

如果幸运的话，您可能会收到社区成员的拉取请求。您可能会发现这对您有所帮助；也许用户已决定对您的问题积压进行一些工作，或者他们已经确定并修复了一些错误-非常棒！但是，并非每个拉动请求都会像这样。您可能会发现某人工作非常努力并且贡献了您不想要的东西，可能是因为这超出了您的项目范围，或者使您的工作变得过于复杂。某些请求请求无济于事-例如，“我为Go重写了应用程序”请求不是您要急于合并的请求。

有些拉取请求会混杂在一起。也许他们添加了两个新功能-一个您想要的功能，一个您不需要的功能-取决于他们的工作方式，您也许可以找到一种解决此问题的方法（查找git ）。但是，有时候，如果不要求他们重新开始就很难解决请求请求。如果是这样，请说明原因，感恩并礼貌。尽量不要忽略它们，因为这可能导致社区成员不满。即使您不打算立即处理捐款，也要发送快速回复说谢谢。

^{本·努塔尔（Ben Nuttall）}

请记住，拉取请求也是问题，因此它们具有问题编号，您可以使用另一次提交来关闭拉取请求，也许是另一次提交可以解决拉出请求试图解决的问题（但以另一种方式）。您可以（尽管不必）通过使用“关闭”关键字引用两个问题编号来自动关闭问题和请求请求。例如，以下提交关闭问题＃123并拉出请求＃124：

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

您还可以对拉取请求提供反馈，并要求用户进行更改，例如是否需要它们添加或删除功能，应用自己的编码标准或基于master分支上的最新版本。如果用户选中了“ 进行框，那么您（或对项目拥有推送权限的任何人）也可以将提交推送到该分支，这意味着您可以在合并之前自己应用这些更改。

当然，可以拒绝请求请求，但是最好总是解释一下为什么要感恩，并尝试确保将来的贡献者不要浪费时间。

发布供款政策

为您的项目提供贡献政策很有用。这使用户可以浏览您的项目，以了解您的准则，期望值，期望人们如何与存储库交互以及在打开问题或请求之前他们应该做什么。

GitHub提供了一种的标准方法：编写准则，并将其发布到项目的根目录（或）中，该文件称为Contributing ， CONTRIBUTING.md或类似文件。当有人创建问题或请求请求时，将显示指向您的策略的链接。

^{本·努塔尔（Ben Nuttall）}

提供开发人员文档

很棒的文档使开始和完成项目变得更加容易。为您的用户提供文档并使其尽可能易于访问是很重要的。不要以为他们像您一样技术娴熟，就可以让人们轻松入门并了解更多信息。编写文档，并保持最新。

^{本·努塔尔（Ben Nuttall）}

但是，文档不仅仅针对用户。如果您曾经尝试过为另一个项目做贡献，则在尝试进行该项目时可能遇到障碍。如果没有说明，则可以运行git clone或尝试在项目中运行一些脚本，然后查看会发生什么—只是找到许多缺少的依赖项以及对已安装内容或对项目的了解的许多假设，或其使用的工具以及它们如何工作。就像不提供用户文档是拒绝潜在用户的最简单方法一样，不提供开发人员文档是拒绝潜在贡献者的最简单方法。

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

许多开发人员认为他们的用户太多了— Linux用户认为其他人都在Linux上； Mac用户认为所有人都在Mac上。 Python用户假定每个人都有pip ，了解virtualenv和许多其他工具，等等。您需要提供安装说明的完整列表，这些说明将适用于尽可能多的人。您需要假设用户没有所需的所有工具，假设他们不了解您的代码库，假设他们不知道什么是点子 -从头开始，并帮助他们到达需要的地方骇客！尽量做到有益而全面，不要屈尊。