【第1842期】如何为开源软件做出贡献

张博轩前端早读课

前言

好久不见，大家好吗？今日早读文章由滴滴@张博轩投稿翻译分享。

正文从这开始～～

如果你和我一样，希望为开源软件做出贡献，又不敢将第一个 pull request 发送至其他团队的代码仓库。

在本文中，我将与大家分享我第一次使用一个主流开源项目的经历。我希望，这将有助于消除使用另一个团队代码工作所带来的恐慌的情绪，并向您展示在更大的社区中工作是多么酷的一件事。

在本文中，我想专门和大家聊聊关于一个 Microsoft’s .NET 文档项目的 pull request。文中所提到的工作流程、工具和示例是该团队，以及参与维护该项目团队特有的，但是广泛的概念应该会适用于你遇到的许多项目。

寻找一个要贡献的项目

毋庸置疑，为了做出贡献，您需要选择一个想要贡献的项目。

上周末，当我得知我已被.NET基金会录取。这对于一个微软死忠粉(从2001年开始就是.NET粉丝)来说是一件大事，这让我想要找到一种方式，来为任何与.NET相关的任何事情做出更多贡献。

碰巧，我在Twitter上发现了一个帖子，激起了我的兴趣：

我决定采纳他们的建议，并查阅.NET文档项目。毕竟，写技术问题对我来说只是一件小事。

选择你的第一个优秀的 Issue

一旦你选择好了一个存储库，你需要找到一种开始的方式。

有时候，你会对一些需要改变的问题有强烈的的看法。其他时候，你可能只是希望帮助团队解决一个炙手可热的 issue。

如果您试图贡献一些特定的内容，您可以跳过本节的大部分内容，转而实际使用代码。也就是说，如果您所做的不是修复一个输入错误或让示例代码正确编译，那么您确实应该在他们的存储库中为您将要进行的工作创建一个 issue。这可以确保您的工作是需要的，并且存储库所有者可以在您为这个主题花时间之前对其实现进行评论。

如果您不知道要处理什么，请转到存储库的 Issue 选项卡，查看所有可用的标记（tags）。想要查看当前开放的问题，并具有“良好的第一个问题”、“可供获取”或应用于这些问题的类似标记。

微软的文档团队已经对他们积压的所有内容进行了彻底的审查和评论，对于我来说，找到可用的问题简直易如反掌。

现在，您需要找到一个问题，它不仅看起来像是您感兴趣的工作内容，而且对新接触存储库的人来说很容易完成。

在我的例子中，我选择了对c#和VB . net中的INotifyPropertyChanged示例的改进。原有的代码很好，但是 .NET 随着时间的推移而发展，并且随着它的发展，出现了更好的实现方式。这是我在自己擅长的领域分享最佳实践的机会，所以我抓住了这个机会。

理解 Issue

当你发现一个现存的问题时，你需要仔细和彻底地阅读它的描述以及它历史上的每一条评论。存储库所有者和问题创建者可能在某种程度上已经加入进来，出于对他们代码的尊重，您应该了解问题及其解决方式的意图和关注点。

在我的例子中， .NET 文档团队非常典型，他们已经彻底审查并讨论了这个问题，我仍然有一些非常有用的意见可供参考。

我还发表了一篇评论，声明了我在这个问题上的工作意图以及我打算做出的改变。在一定程度上是为了看看团队是否会将问题重新分配给我，或者让我重新当成另一个问题来处理，但是没有得到回复。

Fork 和 Clone 代码仓库

虽然您可以在本地 Clone 存储库而无需 Fork ，但是除非您首先 Fork 了存储库，否则您将无法发出 pull request。

值得庆幸的是，Forking 十分简单。只需要点击 GitHub 上的“Fork”按钮，它就会引导你创建一个该存储库的副本。

存储库 Fork 之后，按照 GitHub 的提示将 Fork 的存储库克隆到您的机器上。

GitKraken 是我非常喜欢的一个 Git 客户端，所以我复制了这个 URL 并使用这个 URL 从 GitKraken 克隆了出来，你也可以选择更适合你的方式，比如命令行或者其他的应用程序。

理解团队的工作流程

下一步将根据项目和团队的不同而有所不同。首先，您需要确定应该基于哪个分支进行更改。接下来，您需要了解团队是否选择并专门化了 Git 工作流以及其分支的命名约定。

值得庆幸的是，在大多数存储库中你都不需要感到疑惑，因为社区已经规范了对于 contributing.md 和 readme.md 文件的创建，它将指导您如何开始使用存储库，包括分支结构和 Git 工作流。

如果没有相关的文档就要小心了，因为团队可能不欢迎新的贡献者。

在我的例子中， .NET 文档团队提供了一个非常有用的贡献指南，但是您可能不知道。您可能需要通过查看过去的提交来推断事情，以确定模式，甚至亲自联系存储库所有者。

在开始使用编辑器之前，我建议在 git 中根据适当的开始分支创建一个分支(参见前面的讨论)。一定要检查之前的分支，以及 contributing.md 和 readme.md文档中关于分支命名的描述。

分支名称并不是没有意义的，因为稍后您将向另一个存储库提交 pull request，使用一致的分支名称会帮助你提升归属感。

自我定位

好了，现在您已经在本地获取了代码，您可以在任何编辑器中打开项目，以便处理需求。

在我的例子中，这个编辑器应该是 Visual Studio，但是我在存储库的根目录下找不到 .sln 文件，所以我判定这个项目应该是使用 Visual Studio Code 工作区。

我很高兴地在 Visual Studio Code 中打开文件夹，得到一个提示，当前工作空间与一组推荐的扩展相关联，并询问我是否要安装它们。当然，我接受了这一点，并且 Visual Studio Code 以一种类似于维护者看待代码的方式完成了自我配置。

您不太可能与像Microsoft文档团队这样优秀的团队一起工作(如果您这样做，我相信他们会很乐意听到他们可以改进的地方)。

即使有了这些有用的指导，你仍需要以你自己的方式来理解项目结构。而 contributing.md 可能有助于理解某些文件夹，通常我在项目中的第一步就是打开文件夹和子文件夹，直到我开始看到重复的组织模式。

一旦我熟悉了项目结构，我就开始寻找与我将要更改的代码相关的文件。

在我的例子中，微软通过在GitHub上的问题中标注它们，再次让事情变得非常简单。

因此，对于每个问题，我查找了 how-to-implement-property-change-notifications.md，并查看了markdown文件中包含要更新的代码示例的部分。

令人惊讶的是：

它没有引用包含示例的页面，而是引用了团队维护的另一个git存储库中的示例:样例存储库。

这有点困难，因为我必须 fork 并 clone 那个仓库，然后在项目的结构中找的我要查找的文件。

对我来说，第二个储存库是整个体验中最大的负面因素。嵌套的存储库设计使我更难确定自己的方向，也更难对自己正在做的事情有信心，因为我不能轻易地看到修改后的更改的标记。

我相信微软这样设计是为了让那些想要下载样例并在本地使用它们的开发人员更加容易，所以团队为了更大的社区的利益牺牲了他们自己的生产力。

做出修改并测试

一旦你有了正确的答案，你需要做必要的修正或增强，测试它，然后提交修改后的文件。

构建代码、运行测试、运行 linters (如果适用的话)，以及其他方式验证您的代码都是非常重要的，这是在更大的社区中，成为一个负责任的软件工程师的非常重要部分。

值得庆幸的是，大多数大型项目都在提交请求过程中内置了自动检查，这将确保您的代码符合团队标准，但是在创建 pull request 之前，确保您的代码在本地能够正常工作，这就避免了一些麻烦。

一旦提交了代码，请确保将其推送到了存储库的 forked 版本。为了创建 pull request ，这一步是必要的。

创建你的 Pull Request

现在，你已经推送了你的更改，你可以回到你的 forked 仓库，并通过点击适当的提示来创建 pull request。

左侧的分支和存储库代表要合并到的目标分支和存储库。这个存储库应该是项目的主存储库，分支通常与您的所在分支相同。右边的分支和存储库将是您刚才使用的forked 存储库及其分支。

现在您已经设定了目标，接下来按照团队的约定为您的请求命名。在我的示例中，我将提交的描述性标题和问题编号放在括号中。

团队还使用模板自动填充 pull request 主体的内容，我使用 markdown 语法编写了一个详细的更改列表。

注意，最后一行是 Fixeddotnet/docs#10675 。

这是 GitHub 解析的一个神奇字符串，它将我的提交与文档库中的正确问题(#10675)关联起来(回想一下，我对 示例库 做了更改)。

如果您对将什么放入正在处理的存储库的 pull request 有任何顾虑，请花一些时间查看过去的 pull request 、它们的内容以及关于这些请求的任何注释。

准备好之后，单击 Createpull request。

接下来会发生什么？

祝贺您，您为开源软件社区做出了一点贡献。然而，这一旅程并没有结束。

您的代码可能需要通过自动检查(通常是一个构建，也可能是一些代码分析)，然后才能进行评审。此外，项目维护者将需要检查您的更改，并通过将它们合并到源存储库中来选择是否接受它们。

在我的情况下，更改在第二天早上进行了审核，我收到了一条友好的消息和一个通知，我的 pull request 被接受了，问题也解决了。

我所做的更改在那一天内就生效了，这意味着在我 fork 他们的存储库、进行更改，以及对这些更改进行审查、批准和部署到生产环境之间甚至没有24小时。

总结

正如我所说的，我是微软的死忠粉。然而，当我收到这条信息时，我并没有预料的那么自豪。这是我的提出的一个很小的改变，这个改变是团队使得我很容易完成，但是我为我所关心的事情做出了一点贡献，这让我感到非常自豪。

我强烈建议您尝试一下为开源软件做贡献。找一个你关心的项目，或者感兴趣的东西。如果你找不到任何东西，试着像我一样使用微软的文档，或者在Twitter上发布一些东西，说你正在寻找一些需要帮助的项目。

从小事做起，看看事情是如何发展的，然后逐步发展成你喜欢的样子。

社区是伟大的，如果你遵守他们的规范，代码和工作流程，这通常会对他们产生非常大的帮助，并感谢你提供的帮助——即使你的代码或注释并不完美。

开发开源软件是非常了不起的。它所需要的只是您的一点帮助。

关于本文译者：@张博轩译文：https://segmentfault.com/a/1190000021656000 作者：@Matt Eland 原文：https://killalldefects.com/2020/01/26/how-to-contribute-to-open-source-software/