如何向开源项目作贡献(以 incubator-dubbo 为例)

Github 上有众多优秀的开源项目，大多数 IT 从业者将其当作了予取予求的工具库，遇到什么需求，先去 Github 搜一把，但有没有想过有一天本身也能够给开源事业作一些贡献呢？本文将会以 incubator-dubbo 项目为例，向你阐释，给开源项目作贡献并非一件难事。

1 为什么要给开源贡献力量

为开源项目作贡献获得的收益是多方面的，为了让你有足够的信心加入到开源项目中，我在文章最开始列举出它的诸多好处。

1.1 巩固技能

不管你是提交代码，撰写文档，提交 Issue，组织活动，当你切身参与到一个开源项目中，相关的技能都会获得历练，而且在开源项目中找到本身的位置。一方面，平常工做中咱们中的大多数人接触到的是业务场景，并无太多机会接触到基础架构组件，开源项目为咱们提供了一个平台，在这里，你能够尽情挑选本身熟悉的项目为它添砖加瓦（以 Dubbo 为例，并非全部 IT 公司都有能力自研服务治理框架）；另外一方面，你所提交的代码，会有管理员协助审核，他们会给出专业的建议，更好的代码规范以及更优的编程思路最终都会变成你的经验。

1.2 结交朋友

开源社区为你提供了一个平台，在这里，你能够认识不少纯粹的技术爱好者，开源贡献者是最符合 geek 定义的那群人，你所接触到的每每是某个领域最厉害的那批人。

1.3 创建口碑

这是一个很好的展现我的实力的地方，俗话说：talk is cheap，show me the code. 做为技术人员，没有什么比一个漂亮的 Github 主页更有说服力的了。若是你可以为开源项目作出可观的贡献，你也将收获到业界的知名度，此时开源项目的成就和你是密不可分的。

1.4 传承开源精神

只有源源不断的贡献者给开源项目添砖加瓦，才能够为 Github 一类的开源社区造成良好的开源风气。不然，只有输出没有输入，开源会失去活力。

1.5 养成习惯

相信我，一旦养成了天天提交代码的习惯，就像你不想中断打卡同样，你毫不想中断 commit。不止有英语打卡，健身打卡，还有开源打卡！

2 贡献代码时的一些疑难杂症

若是你是一名开源界的新手，可能会对贡献的流程心生畏惧。好比：我该怎么修改代码并提交？个人代码要是存在bug怎么办？个人代码别人会不会很 low？我该如何寻找合适的开源项目？开源社区那么多的工具和词汇都是什么意思？

文章的第二部分将从一个小白的角度，介绍一下开源中的一些常见问题。

2.1 git 常规操做

通常而言，咱们选择使用 git 来做为版本管理的工具，你不必定要很是熟练的使用它，在我看来掌握 clone，add，commit，pull，push 便可，遇到复杂的场景，你还有谷歌。

fork 与 clone

若是你只是想下载源码，查看他的源码实现，使用 Clone or download 按钮便可。

若是你想要给开源项目作改动，而且最终请求合并，让开源项目存在你贡献的代码，就应该使用 fork。

fork 将会复制一份当前主分支的代码进入到你的仓库中，以后你全部的修改，应当基于本身的仓库进行，在功能开发/bug 修复以后，可使用你的仓库向源仓库提交 pull request。只有源仓库的管理员才有权利合并你的请求。

一些可能对你有帮助的高级指令。

# 设置源仓库
git remote add upstream https://github.com/apache/incubator-dubbo.git
# 拉取源仓库的更新
git fetch upstream
# 将本身仓库的主分支合并源仓库的更新
git checkout master
git merge upstream/master
复制代码

pull request

pull request 常常被缩写为 PR，指的是一次向源仓库请求合并的行为，如上是我 fork 了 incubator-dubbo 的仓库以后才存在的操做按钮。

源仓库视角的 pull request

管理者会对 pull request 涉及的改动进行 review，以确保你的代码是符合规范的，逻辑有没有误差，以及符合框架的功能需求。

2.2 Travis CI

一些自动化的 CI 流程被植入在每一次 pull request 的构建之中，用于给开源仓库去校验提交者的代码是否符合既定的规范，如：是否有编译问题，单元测试是否经过，覆盖率是否达标，代码风格是否合规等等。

通常状况下，必须经过 CI，你的 pull request 才会被管理 review。

2.3 Mailing list

每一个开源项目都会有本身的贡献规范，能够参考首页的 Contributing，来获取具体的信息。incubator-dubbo 做为一个孵化中的 apache 项目，遵照了 apache 的传统，在 Contributing 中描述道：当你有新特性想要贡献给 Dubbo 时，官方推荐使用 Mailing list 的方式描述一遍你想要作的改动。

Mailing list 简单来讲，就是一个邮件通知机制，全部的 Dubbo 开发者都会订阅该邮箱：dev@dubbo.incubator.apache.org。有任何新特性的改动，或者什么建议想要通知其余开发者，均可以经过向该邮箱发送邮件来达到这个目的，相同地，你也会收到其转发的其余开发者的邮件。

或者你是一个 Dubbo 的使用者，你想要得知开发者的改造方向，也能够订阅，这个指南能够帮助你订阅 Dubbo 的 Mailing list。

做为一个 modern developer，你可能以为 mailing list 的交流方式存在滞后性，这样的沟通方式不是特别的高效，但它做为 apache 项目的推荐交流方式存在其特殊的缘由，在此很少赘述。总之遵循一个原则：bug fix或者讨论，能够在 github issue 中进行，影响较大的特性和讨论则推荐在 mailing list 中展开。

3 其余贡献形式

不只仅只有贡献代码，修复 bug 等行为才算做为开源作贡献，如下这些行为也属于主要形式：

3.1 撰写文档

Dubbo文档是其开源组成成分的重要一环，其内容源文件位于：github.com/apache/incu… Git 仓库，任何你想要对 dubbo 知识点的补充，均可以在这儿提交 pull request，只须要一些 markdown 的语法知识，和一些无关紧要的 npm 语法便可。若是你以为贡献代码对于如今的本身仍然有点难度，不妨从贡献文档开始接触开源。

3.2 ISSUE

不管是 Github 中的 Issue 仍是 mailing list 中的讨论，不管是提出问题，汇报 bug，仍是回答问题（bugfix 则不只仅须要 Issue 了），协助管理者 review pull request，都是贡献的一种形式，勿以善小而不为。

3.3 其余行为

任何你可以想到的，能够帮助开源项目变得更好的的行为，都属于开源贡献。例如，给每一个 Issue 打上合适的 tag，关闭重复的 Issue，连接相关联的 Issue，线下组织沙龙，回答 Stack Overflow 上相关的问题，以及文档中一个错别字的修改等等。

4 开源最佳实践

4.1 有效沟通

不管你处于什么样的目的：仅仅是一次性的贡献，亦或是永久性的加入社区，都的和他人进行沟通和交往，这是你要在开源圈发展必须修炼的技能。

在你开启一个isse或PR以前，或者是在聊天室问问题以前，请牢记下面所列出的几点建议，会让你的工做更加的高效。

给出上下文 以便于让其余人可以快速的理解。比方说你运行程序时遇到一个错误，要解释你是如何作的，并描述如何才能再现错误现象。又比方说你是提交一个新的想法，要解释你为何这么想，对于项目有用处吗（不只仅是只有你！）

😇 “当我作 Y 的时候 X 不能工做”

😢 “X 出问题! 请修复它。”

在进一步行动前，作好准备工做。 不知道不要紧，可是要展示你尝试过、努力过。在寻求帮助以前，请确认阅读了项目的 README、文档、问题（开放的和关闭的）、邮件列表，并搜索了网络。当你表现出很强烈的求知欲的时候，人们是很是欣赏这点的，会很乐意的帮助你。

😇 “我不肯定 X 是如何实现的，我查阅了相关的帮助文档，然而毫无所获。”

😢 “我该怎么作 X ?”

保持请求内容短小而直接。 正如发送一份邮件，每一次的贡献，不管是多么的简单，都是须要他人去查阅的。不少项目都是请求的人多，提供帮助的人少。相信我，保持简洁，你能获得他人帮助的机会会大大的增长。

😇 “我很乐意写 API 教程。”

😢 ” 有一天我驾驶汽车行驶在高速公路上，在某个加油站加油的时候，突发奇想，咱们应该这么作，不过在我进一步解释以前，我先和你们展现一下。。。”

让全部的沟通都是在公开场合下进行。 哪怕是很不起眼的小事，也不要去给维护者发私信，除非是你要分享一些敏感信息（诸如安全问题或严重的过失）。你若可以保持谈话是公开的，不少人能够大家交换的意见中学习和受益。

😇 (评论) “@维护者 你好！咱们该如何处理这个PR？”

😢 (邮件) “你好，很是抱歉给发信，可是我实在很但愿你能看一下我提交的PR。”

大胆的提问（可是要谨慎！）。 每一个人参与社区，开始的时候都是新手，哪怕是很是有经验的贡献者也同样，在刚进入一个新的项目的时候，也是新手。出于一样的缘由,甚至长期维护人员并不老是熟悉一个项目的每一部分。给他们一样的耐心,你也会获得一样的回报。

😇 “感谢查看了这个错误，我按照您的建议作了，这是输出结果。”

😢 “你为何不修复个人问题？这难道不是你的项目吗？”

尊重社区的决定。 你的想法可能会和社区的优先级、愿景等有差别，他们可能对于你的想法提供了反馈和最后的决定的理由，这时你应该去积极的讨论，并寻求妥协的办法，维护者必须慎重的考虑你的想法。可是若是你实在是不能赞成社区的作法，你能够坚持本身！保持本身的分支，或者另起炉灶。

😇 “你不能支持个人用例，我蛮失望，可是你的解释仅仅是对一小部分用户起做用，我理解是为何。感谢你的耐心倾听。”

😢 “你为何不支持个人用例？这是不可接受的！”

以上几点，要铭记在心。 开源是由来自世界各地的人们共同协做实现的。面临的问题是跨语言、跨文化、不一样的地理为止、不一样的时区，另外，撰写文字的沟通更是难上加难，没法传达语气和情绪。请让这些会话都充满善意吧！在如下情形中请保持礼貌：推进一个想法、请求更多的上下文、进一步澄清你的立场。既然你在互联网找到了本身的所需，那么请尝试让它变得更好！

4.2 建立 issue

你应该在遇到下列状况下，去建立一个 issue：

• 报告你本身没法解决的错误
• 讨论一个高级主题或想法
• 指望实现某新的特性，或者其它项目的想法

在 issue 的沟通中几点实用的技巧:

• 若是你恰好看到一个开放的issue，恰是你打算解决的， 添加评论，告诉他人你将对此展开工做，并及时响应。这样的话，能够避免他人重复劳动。
• 若是说某个issue已经开放好久了， 这多是已经有人正在解决中，又或者是早已经解决过了，因此也请添加评论，在打算开始工做以前，最好是确认一下。
• 若是你建立了一个issue，可是没多久本身解决了， 也要添加评论，让其余人知道，而后关闭该issue。记录自己就是对社区的贡献。

4.3 建立 pull request

在下面的情形时，请你务必使用 PR：

• 提交补丁 (例如，纠正拼写错误、损坏的连接、或者是其它较明显的错误）
• 开始一项别人请求的任务，或者是过去在issue中早就讨论过的

一个 PR 并不表明着工做已经完成。它一般是尽早的开启一个PR，是为了其余人能够观看或者给做者反馈意见。只须要在子标题标记为“WIP”（正在进行中）。做者能够在后面添加不少评论。

若是说项目是托管在 GitHub上的，如下是咱们总结出的提交RP的建议：

• Fork 代码仓库 并克隆到本地，在本地的仓库配置“上游”为远端仓库。这样你能够在提交你的PR时保持和“上游”同步，会减小不少解决冲突的时间。(更多关于同步的说明，请参考这里.)
• 建立一个分支 用于本身编辑。
• 参考任何相关的issue 或者在你的RP中支持文档(好比. “Closes #37.”)
• 包含以前和以后的快照 若是你的改动是包含了不一样的 HTML/CSS。在你的PR中拖拉相应的图片。
• 测试你的改动！ 若测试用例存在的话，跑一遍，以覆盖你的更改，若没有的话，则建立相应的用例。不管测试是否存在，必定要确保你的改动不会破坏掉现有的项目。
• 和项目现有的风格保持一致 尽你最大的努力，这也就是意味着在使用缩进、分号、以及注释极可能和你本身的风格截然不同，可是为了节省维护者的精力，以及将来他人更好的理解和维护，还请你容忍一下。

5 成为一个开源贡献者

若是你有志于参与开源事业，能够尝试从本身最熟悉的项目开始，开源并非属于高级开发者的专属词汇，它就是由你我这样的人在需求，修复，构建中演进下去的。Let's try it !

参考资料 如何为开源作贡献

欢迎关注个人微信公众号：「Kirito的技术分享」，关于文章的任何疑问都会获得回复，带来更多 Java 相关的技术分享。