零起点的开源社区贡献指南

作者:doodlewind

原文地址:https://juejin.im/post/59f98a196fb9a045132a03ed

【开源社区贡献者】听起来是个专属于顶级开发者的头衔，但它真的有这么遥不可及吗？下面的分享旨在揭开它的神秘面纱，帮助感兴趣的同学更轻松地参与到社区项目中来。

首先需要澄清的是，本文作者自己并不是社区高大上项目的原创作者，只是在一个 5k+ Star，100+ 贡献者的项目中贡献排名前十而已（作为参考，Vue 的贡献者不到 150 人），和《维护一个大型开源项目是怎样的体验》这个问题里闪耀的群星相比，只不过是个小透明的存在。不过因为自己也只有一年有余的经验，在很多方面上和刚刚入门的新人同学们都很相似，因此相信个人经验能有一定的参考价值，才在此做了些总结。文中如有不妥之处，请 dalao 们斧正。

下文内容主要分为这两部分：

起步与进阶，介绍在对编程一无所知的时候，能够通过什么方式参与到社区中来。以及在有了贡献的条件后，如何通过 Issue 和 PR 在开源项目中协作。
技巧与总结，介绍一些技术性的细节，以及如何在 Github 上商业互吹的沟通技巧。

起步

参与开源项目的主要方式，由易到难不外乎这三种：

翻译文档
报告 bug
提交代码

在起步阶段，翻译文档的难度无疑是最低的。因为这甚至不需要你编写或运行任何代码，只要在编辑页面里翻译就足够了。

以 Mozilla 维护的 MDN 文档为例，也许有不少同学不知道，MDN 文档和维基百科一样，是允许所有用户编辑的。比如，一篇介绍 CSS 定位方式的 MDN 文档，页面顶部大概长这样：

mdn-large

注意到 Languages 和 Edit 了吗？你可以在 Languages 里选择你需要的语言，或者添加新语言的翻译。如果已有翻译，可以直接点击 Edit 编辑！

在翻译时，Mozilla 的富文本编辑器会分为左右两个部分，可以直接对照：

mdn-editor

现在只要点击保存，你就会出现在这个页面的贡献者里了！你的更改也会在文档历史中保存，所以在提交前不妨检查下内容吧。另外，并不是一次保存就必须搞定一整篇文档，写到一半准备保存的话，可以点击页面最下方的 本地化进行中 选项，这样就能够在浏览页面中添加一个【翻译正在进行中】的标识啦。

这个过程里我们似乎一行代码都没有写，那么这有什么用吗？个人的观点是，翻译文档是一个很好的开始，因为它可以：

帮助你更好地理解英文技术文档的行文结构，为后面和其他开发者的交流打好基础。后面我们也会提及，很多时候需要为一两行代码编写的文档远远不止一两行。
很大地锻炼你的行文水平。在初期你可能会写出比较翻译腔、不通顺的技术文档，熟悉以后会有很大的进步。
让你的贡献迅速地得到反馈。MDN 的权重在 Google 并不低，通过 Google 在第一页查到你翻译的内容，还是挺有成就感的。
提高你自己对文档内容的了解。以作者本人为例，在了解富文本编辑领域时首先就是从搬运 Mozilla 中的富文本编辑器文档作为开始，完成翻译后就这个领域内的基础概念了然于心了。

除了 MDN 文档外，中文技术社区也有不少优秀的相关项目可以参与。这方面个人的参与不多，就不班门弄斧了。

进阶

只是翻译文档的话，你可能很快就会达到【写腻了】的阶段，这时候就不妨来看看更大的世界吧。找一个 Github 上的活跃项目作为开始吧！对于在 Github 上维护的开源项目，主要的参与方式包括 Issue 和 PR 两种：

Issue

对一个中大规模的开源项目，Issue 主要用来：

报告 Bug 与提问
提出并讨论新特性
设定 Todo 目标

需要注意的是，许多项目是有自己的 Discuz 论坛或 Slack 群的，有一些类似【为什么安装失败了】的新手向问题可以先在已有 Issue 中搜索，然后再在论坛和 IM 中提出。如果随意地提出 Issue，很可能会得到 Duplicateof#xxx 的回复然后被关掉。对于新同学，一个非常好的参考是《提问的艺术：如何快速获得答案》。

只要给项目提出过 Issue，你当天的 Github 贡献图就会刷绿，并且也能够把这个项目固定在个人主页里了！看起来同样不需要写代码，并不难呀。不过，单纯地提 Issue 并不会让你出现在项目的贡献者列表里，如果想真正地【贡献】代码的话，PR 是必须的。

PR

Pull Request 顾名思义，就是请求别人拉取你的代码的意思。这是十分符合开源工作流的：开发者们 fork 出自己的仓库，在自己的分支里 commit 代码，然后请求维护者将自己的更改合并进来。一般而言一个 PR 只要做好一件事情就足够了，其作用不外乎以下之一：

修复 bug
实现新特性
优化性能
例行更新（如文档、依赖版本等）

新同学如果想要贡献 PR，不妨先从自己擅长或关注的方面去着手，比如一些简单的文档拼写错误，或者标记为 help please 一类的 Issue。

只要提出 PR，不论合并与否当天的 Github 贡献图都会刷绿，而 PR 合并入主干时，当天的贡献图也会刷绿。假设你发现了一个小 bug，只要一行就能够修复，那么整个流程走下来大概是这样：

提出 Issue，贡献 +1
提出 PR，贡献 +1
回复维护者的 Review 评审，贡献 +1
PR 通过，贡献 +1

所以，哪怕仅仅提交一行代码，最多也足够点绿四天的贡献图了。并且，维护者们在 Review 或并入你的 PR 时，他们的贡献也会相应增加。这样想来，大型项目贡献者们一年动辄几千的贡献数量也不是只能让人仰望的了吧。

技巧

上面仅仅介绍了开源工作流中的几个基础概念。在真正参与时，还有一些可以稍加注意的技巧。下面介绍的就是一些与此相关的小细节。

问题导向的源码阅读

在需要提出 bugfix、新 feature 或性能优化类 PR 的时候，阅读框架源码基本是绕不开的。当然，我们经常能够在技术社区看到很多【源码解析】类的文章（在近期以 Redux / Vue / Koa 为甚）。作者写这些文章的出发点肯定是好的，不过令人有些遗憾的是，许多这类文章的阅读量相对并不高，并且多数这类文章的作者并不是这些框架的贡献者。

是我们太浮躁了吗？我们不妨从动机上考虑一下，我们为什么需要阅读源码呢？是为了解决实际遇到的问题，还是仅仅为了写一篇博客来展示自己的技术水平呢？如果只是贴上一个个看起来高大上的代码截图，然后把注释翻译成中文，这样的文章对读者、对社区又有什么帮助呢？【我读过这个框架的源码】和【我修过这个框架的 bug】相比起来，哪个的贡献更大呢？

个人的观点是，带着问题去调试源码，收获会比简单的阅读理解大很多。在你真正需要解决一个 bug 的时候，你才会真正去思考调用的顺序、执行的流程、变量的意义，然后在一个个断点、日志和错误堆栈的帮助下，真正知道一些看起来漫不经心的判断是多么不可或缺，看似简单的地方又隐藏着怎样的预设条件。

从这个角度而言，以修复 bug 的动机驱动去维护开源项目，对技术水平的锻炼，会比在单纯的源码阅读或在技术社区里逛博客点赞要来的更高。而每一个发展中的项目，都会有不少已发现或未发现的 bug 等待我们去修复。在这个参与的过程中，你的工作不仅能让社区收益，也能够更多地让自己获益。

不过，【如何阅读源码】已经脱离了本文的讨论范围。在此我们点到为止就足够了。

友善的互吹评价

参与开源项目和搬运文档相比，很重要的一点区别在于和其他人之间的互动。你的 Issue 会有人评论、代码会有人 Review，PR 也会有人点赞。这时候，和其他人的互动是少不了的。在 Github 这样的英文技术社区，合适的交流方式对促进社区发展是很有帮助的。

这里我们只分享一点：如何更友善地对其他人的工作作出评价。在中文社区，除了【伸手党】以外，还经常能够看到【喷子】直接抨击项目质量或者给人盖上【抄袭】的帽子。不过，吐槽别人的代码肯定是少不了的。在社区中交流时怎么样更委婉地指出 PR 的问题或在 Issue 中回复观点呢？

很有趣的一点是，在 Github 上很少看到这些词：

bad wrong dirty terrible ***...复制代码

更基本看不到这样的说法：

I think this code is bad and do things wrong!复制代码

与直接吐槽代码 bad 相对地，不妨这么说：

表达 API 笨重不好用，可以说 heavy to workwith
表达模块结构不好，可以说 notintuitive
表达处理方式太粗暴，可以说 overkill
表达逻辑可能有漏洞，可以说 leaky
表达要引入的东西太多，可以说 aggressive
...

而 I think 则显得非常武断，可以这样：

万能的 IMO 或 IMHO，即 Inmy(humble)opinion
补充一个 Notsure,maybe missing something
用 Tomyknowledge 或者 Forme

以及，在请求其他贡献者 Review 或合并时，记得加上 Wouldyou please 和 Couldyou please 也是很不错的。哦对了别忘了 Thanks 啊。

总之探索合适的沟通词汇是一件很有趣的事情，不过对英语的要求并不高，运用上面的介绍其实只要初中英语水平就足够了吧…相信有兴趣的同学能够总结出更多【开源黑话】