【译】如何为开源软件作出贡献

原文： How to Contribute to Open Source Software
做者：Matt Eland
译者：博轩
为保证文章的可读性，本文采用意译，转载请保留原文连接

前段时间参加了2020年1月11日Node party线下分享，justjavac 大佬分享的主题就是：《如何融入并贡献开源》（相关PPT，以及连接），感触颇多。今天又看到一篇讲关于如何参与开源的文章，就想翻译下，与你们分享~

原文地址

若是你和我同样，但愿为开源软件作出贡献，又不敢将第一个 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 语法编写了一个详细的更改列表。

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

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

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

准备好以后，单击 Create pull request。

接下来会发生什么？

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

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

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

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

总结

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

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

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

社区是伟大的，若是你遵照他们的规范，代码和工做流程，这一般会对他们产生很是大的帮助，并感谢你提供的帮助——即便你的代码或注释并不完美。

开发开源软件是很是了不得的。它所须要的只是您的一点帮助。