一份程序员必备的开源指南

作者：Ken Wheeler

翻译：EE （开源社文案翻译组成员）‍

来源：开源社

原文：https://medium.com/codezillas/a-bitter-guide-to-open-source-a8e3b6a3c1c4

嗨，我是 Ken.

我在世界上最好的公司 -- Formidable 担任开源总监。‍

如果你以前听说过我，可能是因为那么一两件事：

• 在 Twitter 上废话连篇

• 开源数据库，例如 Slick Carousel, Webpack Dashboard, Spectacle, Cash 等等

今天我们要谈的，主要是第二件事。最近（以及过去）有不少人问我能否围绕开源做些指导，那么今天我的确想写一下这方面的内容。

在开始讨论技巧之前，我想先谈谈为什么要做开源项目，以及我自己的经验。

你为啥应该写开源软件？

关于为什么，有很多原因可以解释为什么开源对你和你的职业发展来说都是一件好事。

• 它可以为你的个人声誉增添色彩。如果你有一个受欢迎的项目，大家就会熟悉你和你的工作；

• 它对你的公司品牌有极好的影响。提供和维护一个开源作品集能提高品牌知名度。让员工有时间在开源上面投入，看到他们的想法变成现实，恰能证明你所在的公司是一个很好的工作场所。

• 你可以成长为一个名副其实的开发者！你不再是在 /Users/Me/devshit 文件夹中编写没什么人看的业余项目脚本，那么多少双眼睛盯着呢，所以你有动力让事情推进下去。

• 你是在帮助他人。你因为 John-David Dalton 的 lodash 从而在项目上节省了时间，同样，别人也可能会因为你写的代码节省下时间。你成为了社区的一部分，在这里，合作和分享使得大家都可以节约时间。

• 这种感觉很棒。虽然说的是个人的感觉，但每次有人因为某个项目对你表示感谢，或者告诉你因为你的代码节省了他们时间的故事，你会感觉非常爽。

• 这可能不会给你带来一份工作，因为大多数公司不会严格地按照 GitHub star 来招聘员工，但是如果说对你面试没有帮助，那我就是在说谎。

我在开源软件上的经验

先来谈点别的。我算是有史以来最差的开源维护者了。

好吧，就算不是最差的，至少我每次都没有尽力做到最好。

我有很多次都没能妥善管理好开源项目，要不是当初创建他们的时候还算成功我肯定凉透了。

不过对于每个项目，我都从失败中吸取了教训，并且利用从中得到的见解来帮助我下一次做得更好，这些我在后面会介绍。我在这方面肯定会变得更好，但我也希望读者们能从我的错误中汲取教训，而不是重蹈覆辙。

我简短的说下自己的经历，因为跟典型的开源软件经历相比，我的有点“不走寻常路”。不管你信不信，在我整个职业生涯中我可能只对不属于我自己的大概20个项目做过贡献。我只是写一些东西，然后把它发布出去。

我觉得把这些介绍一下，不管从个人角度还是从事件背景来说，都还挺重要的。

我的第一个开源软件项目大概是我最成功的一个项目了。记得那时我在一家广告公司工作，给位于纽约的大型时尚品牌创建电商网站。我是团队里的高级开发人员，通常被安排做大量的JS开发工作。跟我一起回到 jQuery 时代吧。。。

关于时尚电子商务一件很有趣的事情是，几乎到处都在使用 carousel。电商网站往往进行精心，复杂，雄心勃勃的设计，结果导致现有的 carousel/slider 库不够灵活，难以实现我所要达到的设计目标。于是，我就自己从头开始用 CoffeeScript 编写 carousels。 这玩意儿虽然行得通，但是当然并没有让我在同事当中更受欢迎。

所以我看到了一个明确的需求。得有一个足够灵活的 carousel 插件来应对设计师们丢来的各种东西，使用方便，易于修改。于是，我把它写出来了。为了我们团队。然后我又想既然这么有用，为什么不让别人也节省大把时间出来呢，所以，我将它开源了出来。。。

事实证明它的确为其他人节省了大量时间，大家似乎挺喜欢它。在我发布它之后的头几个月，其热度简直突破天际。我是开源软件的新手，看到大家都在用我写的东西自然是感到无比兴奋，于是我整夜不眠不休地快速解决问题，发布新版本，确保没有人能与之匹敌。

我在这里稍微说得简短一些，毕竟这是一篇有关技巧的文章，不是讲我的故事：最后，我对这个项目不再关心了。我把这归因为几件事上。我换工作了，所以我实际上不再需要用到 carousels ，我已经置身于问题空间之外。React 出来了，我很早就开始用 React，所以兴趣自然不会再在 jQuery上。

但是最大的原因之一还是因为我感到筋疲力尽了。我在这个项目上投入太多。而评论里面各个都自以为是，抱怨我们不应该使用 carousels （即使每一个赚钱的项目都有一个，而且我还只是拿到了递交过来的设计而已），我变胖了，惹得我妻子很生气。

此后，我在不同领域又做了几个流行的库，每一个都用来解决不同的问题。我最大的恐惧之一是我再也写不出来一个流行的库了，担心打击会随之而来。我逃避到现在，我可以一直去写一些中规中矩的东西，但有一种困扰却挥之不去-- 我因为管理该死的 carousel 让大半个互联网限于瘫痪。

所以，下面就是我的开源软件技巧，希望你可以用到它们，做出成功的项目必须付出相应的努力，而不是用威士忌来减轻开源带来的负罪感。

开始

开源很像做演讲。许多人认为他们推销给别人的东西价值不高。这简直大错特错。如果你读过关于“冒名顶替症候群”的文章，你会发现事实就是这样。每个人都有自己的知识领域，一个人不可能通晓所有知识点。总会有人需要你兜售的东西。

我有两个独特的优势：a）关我屁事 b)迷之自信，所以我只管把东西写出来，我知道这两点对很很多人来说比较难。我的建议是：

尽管去做！

可能出现的最坏的情况？人们会说难听的话？我来告诉你，孩子，哪怕你拿出最完美，最有用，最打动人心的代码，把他们放到GitHub上，你猜会怎么着？照样有些二货会进来吐槽发牢骚，这是不可避免的。在最坏的情况下你也能学到一些东西。有人会这样说，“嘿，这搞得性能像坨屎”，你可能会回答说，“额。。。我不擅长编程，算了我退出”，但是你也可能这么回答，“”太棒了，多谢你的提示，我刚修复好了，现在好点了”。要成为那个让事情变好的人。

所以你要在哪方面造*？好吧，这个问题可是价值百万美元啊。

我是这么看的：

• 你有一个问题

• 你有解决这个问题的方法

• 你把解决方案包装得非常好，大家都想用你的方案来解决他们的问题

那么，我们就来谈一下怎么包装。。。

API 设计

所以你有了自己的想法。以前你遇到过一个问题，现在你已经把它解决掉了。但是你想让其他人也用你这个方法来解决问题对吧？以下就是一些提示，告诉你如何让别人也想用你的东西。

首先也是最最重要的，看一看竞争对手和现有的技术。如果你和其他人的库做得一样，那就需要做些东西将它们区别开来。举个例子，你想要开发下一代 lodash。

祝好运（不好意思不得不完成它）。但是除此之外，为了争取到 lodash 的市场份额，你得有吸引人之处。你的东西必须要有更小，更快，或者更好的 API。 明白我要讲什么了吗？

说到 API 设计，就需要做一定的取舍。你可能做了一个库，开箱即用，但是有人会抱怨说想要调整参数。你可能做了一个史上最灵活，可配置的库，但是你就变成了 Tobias Koppers/ Sean T. Larkin，大家会抱怨为什么还要去配置（Sean，对不起，我是*这么说的。你的v4版本做得非常好）。

你想找到其中的完美平衡，既要开箱即用，又能在必要时进行配置。最重要的是，你想要让一切变得简洁，明确，容易上手。不要聪明过头，否则你会把所有人惹毛！

我喜欢做的一件事是用一种非常明确而非聪明的方式写我的源代码。因为这样可以让别人更容易参与贡献。进行适当的标注和说明，不要搞自嗨式编程，如果你准备搞一个 hack，留下评论解释下原因。

这段时间以来我没有写一行代码，直到我完成了一个心目中想要的模拟的 API。如果你要把它做成真正的 API 的话是要花些时间的，但这是一个值得努力的目标。你会知道什么时候 API 做对了，因为那个时候你会有想要使用它的感觉。

准备发布

所以你已经在往前走了，解决了问题，将解决方案包装的不错，一切准备就绪，是时候发布它了。但是在此之前，如果你想让人们使用它，还有些事情必须要做。

一些该死的文档要写

我真不是在开玩笑。你要写的必须是史上最好的文档。避免写一些像“just”和“simply”这类显示优越感的字眼。你的文档开头要有一个标题链接索引。在入门部门，必须详细地解释清楚第一次用这个库时该怎么用。对于 API 的每一个犄角旮旯都必须编进文档，以详细到荒谬的地步全部写出来。如果你有一个方法，你应该把预期的参数，类型和返回类型都编进文档。你应该记录它的功能。应该举例说明怎么用。让别人很容易就能使用你的库。

你应该在文档中说明如何做贡献。你应该在文档中说明如何运行所有这些编译的步骤。如果你引用了另外一个项目，或者任何一个概念，都要提供对应的链接。如果你引用了任何可以链接的东西，请把链接加上。

文档工作要做得彻底，这会让你的项目有很大的不同。

一些该死的测试要写

听我说完。你应该把测试覆盖到合理的占比。原因在于：

• 它使你对自己库的稳定性有一定的自信；

• 它将使你在合并 PRs 时更有信心；

• 它让你在离开这个项目一段时间后再回来仍然满怀信心地为它工作。

有一次我发布了一个库，没有做测试，Paul Irish 随口说了句，“如果测试一下会很酷”。Paul说话了我还有啥好说的，就乖乖去写测试了。没想到，我竟然找到了 15 个bug！感谢 Paul！

强烈建议，不管你做了什么东西，都写一些该死的测试。锦上添花哦。它为我节省了很多时间，心情也没那么糟。

写完测试之后，把它在 Travis 或者别的什么地方设置好，然后你就可以安心睡觉去了。

使用类型

测试没有覆盖到的，类型来补救。现在如果你不对你的 JS 划分类型，就好像开车没系安全带。此外，随着越来越多的人使用 TS 或者 Flow，他们开始希望类型已经就位。用类型编写库，导出和提供类型，你会感谢我的。否则后面让别人标注类型，那就是第三方风格的，过时的，还可能是错误的。你看着办吧。

Repo （代码库）的先决条件

• README.md

• CONTRIBUTING.md

• LICENSE.txt

• 一个有效的，完整的 package.json

README，就不说了。你应该始终包含一个 LICENSE.txt，否则有些人就用不了你的代码库。授权用 MIT 协议。不要自作聪明自己写一些授权声明。就用 MIT。用它就对了。

CONTRIBUTING.md 是个好地方，不仅可以规定如何为项目工作，还可以链接/添加行为准则。添加行为准则，不管你是否认同这个概念，相信我，它会让贡献和参与项目的一些人感到舒服，今后你要是遇到问题了，也可以把它祭出来踢走令人讨厌的人。

加分项

假设你已经写出了很棒的文档，API 设计紧凑，所有的先决条件已经就位，这时候你开始准备让代码库在发布之前看起来像模像样了，这里我有些建议。

徽章。没有什么能比徽章让你的 repo 看起来更正规的了。徽章太多看上去乱七八糟，但是如果你抓住有用的几个，那就是合法性的标志。说明你关心合法性这件事情。像 npm 版本，测试状态，覆盖率等等都是很好的徽章。

此外，Mardown 支持原始 HTML，这会让你的代码库标题看上去更漂亮。居中，加一段引言，美化一下。

如果你真的想做到最好，那就在这里 https://github.com/kentcdodds/all-contributors 添加贡献者名单。这是非常好的方式来认识为这个项目做出贡献的人。天哪， Kent C. Dodds 真是个好人！

发布和推向市场

一切都恰到好处，是时候闪亮登场了。你怎么让大家过来看看并使用你的新库呢？

我有一条特别建议。周一中午12点（美国东部时间）发布。这个时间，在欧洲正好是下班时间，在纽约是午餐时间，在旧金山是早晨--忙碌的一天即将开始。你有一大批目标观众正无所事事地在网上闲逛呢。

至于如何发布，我认为 Twitter 是第一站。表达夸张一点，

“厌倦了敲键盘写 CSS? 你现在可以用一个 XBox 控制器写啦！”，

“堆栈跟踪让你掉进了沟里？如果他们可以用炫酷的 VR 进行跟踪呢！”

做自己想做的。但是要有吸引力，并且使用图片，或者视频。让人立马了解这个东西是什么，为什么他们要使用它，给一个链接。过程大概是：

• 浏览 Twitter

• 噢，看看这条推送

• 什么玩意儿！这东西居然能做这个？！

• 点击链接

• 进入到代码库，感觉还挺酷

• 点击开始

• 复制/粘贴到终端，放开浪

• 【点击开始按钮】

你能走多远，就要看你的粉丝量以及你向他们推销的技术方向，这通常是有效的招数。除了 Twitter, 在 HN 和 Reddit 上发布效果也不错。

另外，如果你觉得有必要，就在发布的时候附上一篇博客文章，尤其是以公司的名义进行的发布。你可以用更长的内容来展示它。

要大胆。要自信。准备好迎接外界的批评。

维护

我一直害怕到这一步，因为一到这里，我的经验总会把事情搞得一塌糊涂。但是我很高兴能和大家分享我从各种失败中得到的教训，希望大家能够了解接下来会发生什么事情。

现在你发布了库。它有两种结局：

以失败告终

谁会在意呢？我总是碰到这种情况，重头再来呗。有时候没火起来并不代表你很失败或者你的想法不行。只是没到火候而已。重要的是你做了，你做对了。当你下次再开发东西的时候，你离成功会更进一步。给自己点鼓励，重新出发！

大受欢迎

这才是真正让你头疼的呢。大家喜欢你的东西。在 twitter 上转发。这时你要不断地修复 bug，回答问题，捍卫自己的想法。对此我有一些建议。

首先，如果任何人对折腾你的库感兴趣，就将他们发展成 maintainer。坚持这一点很重要！因为随着时间流逝，新的技术不断涌现，随之会产生很多新的问题。你自己也会变。而你的代码库还在那里。如果你不委派别人，就等于给自己挖了个坑。你会因为维护而累得精疲力尽，会开始厌恶自己的项目直到它烂成一坨*。相信我，交给别人去维护。

接下来，我要谈谈怎么与人相处。

这是开源最大的部分之一。很多时候都比写代码更加重要。人们开始吐槽你了，他们各个都觉得自己有这个资格，他们会公开攻击你的项目。

理这些人干嘛！

我浪费了很多时间跟这些人理论，现在我希望这些精力能花在别的地方。相信我，让喷你的人见鬼去，别理他们。

但是，要注意鉴别喷子。有的人看上去像喷子，其实并不是。想一下，你是在向全世界发布开源项目。假设你是美国人，发布的时候使用的是英文，请记住不是每个人都会说英语。

想象一下你想为一个用俄语写的代码库做贡献。但你不懂俄语。于是你用 Google Translate 将这句话翻译成俄语， “嗨，这个项目有实现的时间表吗？”。然后比方说俄语翻译过来是，“这个什么时候能完成？”。乍一眼看过去你可能会觉得，“嗨，这家伙是不是有毛病啊？”，但是后来你才意识到在互联上意思的传达做得不是那么好，经过翻译传达之后就更加不对劲了。

要注意的是，有时候别人不是笨蛋，他们只是不会说你的语言罢了。

除此之外，我能告诉你的最好的方法就是你的 PRs 要有一个牢靠的 CI （持续集成），要列出 issues，要有 PR 模板。在代码库上你会遇到成堆的 issues 和 PRs，如果想要管理好它们，你得树立一些基本规则。我的建议是：

• 要求重现案例或者失败测试案例

• 要求提供 bug 产生的情形

你是没有时间找出某些一次性的 bug 的。让用户向你证明这个 bug 的存在并且让你易于识别。这样你才会花时间去修复它。

而且，在 CONTRIBUTING.md 的某处指出大家应该在处理 PR 前在 issue 里面跟你先讨论想法是值得的。世上最悲哀的事情莫过于努力地去处理一个永远都不会被接受的 PR。

谈到接受 PRs，在这一部分我最后想说的就是你不必去做别人要求你做的事情。我就因为屈服于用户而浪费了很多力气就为做个 API 出来。

大多数时候，有些人只是因为他们遇到的一个孤立的小问题而需要一些东西，但是这对整个广大的社区是没有价值的。要警惕对你的 API 的任何改动，因为那些带着极端需求的人会把你的 API 搞得一团糟。要为核心库做正确的事情，而不是帮一些搞滑翔机遥测系统的家伙去解决问题。

哦，我说谎了，我要说的最后一件事应该是：正确地使用语义版本控制。

一定要这么做。否则，每个人都会失去理智的。还有推送标签。还要写版本说明。详细的版本说明。随着你的库的不断演进，让投入到里面的各方知道发生了什么是非常重要的。

保持透明，清晰和信息健全。不要在没有宽限期的情况下弃用任何东西。如果大家用了你的库，而你继续改东西，让他们的应用程序出问题，别人是不会开心的。以一种富有同理心的方式去升级你的库。

总结

到此为止，你大概明白了我不止在开源软件上做得很糟糕，写文章也不在行。但是既然有人在问，那我就写了。我希望这篇流水账能够帮助到那些想发布自己的开源项目的人，让他们能节省一些时间和精力。

这里面要注意的事有很多，但是如果你每一样都能符合要求，你的日子会比我好过，成功的机会也会更大。

尽管如此，我还有最后一个建议。除非你真的想做，否则就不要做。不要觉得这是你必须做的。不做这个，你一样可以找到工作。不做这个，你一样可以成为好的开发。我从中获益匪浅，也享受于此，但是我永远也没法把我免费花在库上的时间给找回来了，那些时间我本可以用来陪伴家人，追求自己喜欢的事情，做任何可以给我带来可观收入的事情。因为想做才去做。如果你对自己开发的东西没有激情，可能就不会成功。