开源项目：普通人的禁区，苦涩的真实指南

嗨，我是KEN。

我是世界上最好的公司-Formidable 的开源总监。

如果你以前听说过我，可能是两件事中的一件，或者两者都有：

• 1、看我在推特上说一堆废话

• 2、你了解开源库，比如Slick Carousel, Webpack Dashboard, Spectacle, Cash等等……

今天我们聚焦第二点。最近(和历史上)有很多人希望得到关于进行开源项目的指导，这也是我想写的内容。

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

为什么你要写开源软件？

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

• 为你的个人品牌创造奇迹。如果你有一个受欢迎的项目，人们就会熟悉你和你的工作

• 为你公司的品牌创造奇迹。提供和维护一个开放源码组合可以给品牌带来可见的价值。给员工时间去做开源，看看他们的想法同时能让他们明白公司是一个很好的工作场所。

• 你可以成长为一个开发者!你不只是在你的/Users/Me/devshit这些文件夹中编写一些附加的项目脚本。而是关注这项目，保持动力去推进。

• 你的回报。就像你使用John-David Dalton放弃了lodash从而在项目上节省时间，你可以用你的代码节省其他人的时间。你们成为了整个社区的一部分，在这个社区里，合作和分享使大家都可以节约时间。

• 很棒的感觉。就我个人而言，每次有人感谢你的项目或者告诉你你救了他们项目的故事时，你都会有一种奇妙的感觉。

• 这可能不会给你带来一份工作，因为大多数公司不会严格地基于GitHub星级来招聘员工，但如果说这对你的面试没有帮助，那我就是个骗子。

我的经验

换个话题。我是有史以来最差的开源维护者。好吧，也许不是最坏的，但我没有每次都做到最好，经历了多次失败。但是在每一个项目中，我都从失败中吸取了教训，这些教训帮助我做得更好，我将在后面介绍这些。希望读者能从我的错误中吸取教训。

简单地写一下我的经历，因为与典型的开源软件项目经验相比，有点非传统。信不信由你，我认为在我的整个职业生涯中，对非我自己的项目所做的贡献可能不到20个。我整理一些东西并写出来，我认为这些背景很重要。

我的第一个开源项目可能是我最成功的项目。我在一家公司工作，为纽约的大型时尚品牌创建电子商务网站。我是团队的高级开发人员，通常被要求做大量的JS开发工作。和我一起回到jQuery时代…

这是有趣的是时尚电子商务系统，几乎到处使用轮播。他们精心对系统进行复杂的、雄心勃勃的设计。现有的carousel/slider库不够灵活，无法支持设计目标，因此我开始从头开始用CoffeeScript编写carousel。它起了作用，但它肯定没能让我在同事中获得任何声望。

我看到了一个明确的需求：需要一个carousel插件，足够灵活的支持任何设计，易于使用，易于修改。我觉得这很有帮助，为什么不节省大家的时间，所以我将它开源……

结果证明它确实为其他人节省了很多时间，而且人们似乎喜欢它。在发布后的头几个月，它的受欢迎程度达到了顶峰。我是OSS的新手，对人们真的在使用我的东西感到非常兴奋，所以我会整夜不睡地快速解决问题，发布新版本，确保没有人能与之竞争。

最终我不再关心这个项目。我把它归结为几件事。首先我换了工作，所以我不再需要carousel了，对jQuery的东西不再感兴趣了。但其中一个最大的原因是我已经筋疲力尽了。我太努力了。我读了所有评论，人们都很有权利，很固执己见，人们抱怨我们不应该使用carousel。

从那以后，我在不同的场景使用一些流行的公共库，每个库都解决了不同的问题。我最大的恐惧之一是我再也不会写一个流行的库了，我的热门作品已经被我抛在脑后了。到目前为止，我一直在逃避，有一件事一直困扰着我，那就是我觉得我用那个该死的carousel让一半的互联网都瘫痪了。

这是我的OSS提示，希望能帮你并且你有成功的项目，而不是用威士忌来减轻开源的负罪感。

开始

开源很像演讲。许多人认为他们卖的东西不够有价值，这是废话。如果你读过关于冒名顶替综合症的文章，你会发现那篇文章是完全正确的。每个人都有自己的知识派（knowledge pie），没有一个人拥有整个派。总有人需要你卖的东西。

我有一个明显的优势:a)我一点不在乎和b)有非常的自信，所以我只管把项目扔出来，但是我注意到这对很多人来说很难。我的建议:

只管去做

可能发生的最坏的情况是什么?人们会说些废话吗?我有个消息要告诉你，孩子，你可以把最完美、最有用、最让人抓狂的代码放到GitHub上，你猜怎么着?一定有个混蛋会进来发牢骚的。这些都是不可避免的。

最坏的情况，你会学到一些东西。有人可能会说，“嘿，这让性能很糟糕”，你可能会说，“哦，我不擅长编程，我退出了”，或者你可能会说，“哦，谢谢你的提示，刚刚修好了，现在好多了”。这些经历会促使你做一个能让事情变得更好的人。

那么你应该建造什么呢?这就是价值百万美元的问题!

我认为是这样：

• 你有一个问题

• 你提供解决方案

• 您提供的解决方案非常好，以至于人们希望使用您的解决方案来解决他们的问题

所以我们来谈谈如何把它包装得很好……

API设计

当你有自己的想法。你发现问题并解决了它。但是你想让别人用对吗?这里有一些让别人用你的技巧。

首先也是最重要的是，看看竞争对手和现有技术。如果别人的库做了和你一样的事情，你需要一些东西来区分它。假设您想构建下一个lodash。祝你好运(对不起，我得把它弄掉)。但除此之外，为了打入lodash的市场份额，你需要有一个hook，它必须更小，或者更快，或者更好的API。看到我要讲什么了吗?

谈到API设计，要考虑各个方面的平衡。例如你做了一个库，开箱即用，但是使用者可能想要调整参数。那么你要考虑如何实现最灵活、可配置的库，不仅开箱即用，还要在必要时候进行配置。

除此之外，你还需要保持代码编写清晰、明确。

我喜欢做的一件事是用一种非常明确而不是炫耀聪明的方式来写我的源代码。这让你更容易做出贡献。明确代码的作用是什么，不要只有你自己知道做什么的函数编程，要进行适当的标注和说明。

准备发布

你解决了问题，把它包装得很好，一切都准备好了。现在是时候发布了。但在此之前，如果你想让人们使用它，需要做一些事情。

写文档

我不是在开玩笑。你需要的是有史以来最好的文档。避免说一些像“公正”和“简单”这样带有居高临下色彩的废话。在文档顶部有一个标题链接索引。你需要一个入门的部分，解释如何第一次运行系统的细节。你要把API的每一个细节都记录在文档中。

如果有一个method，应该对预期的参数、类型和返回类型进行文档化。完整记录它的功能。你应该举例说明如何使用它。让你的库更容易使用。

文档中要包括如何贡献，参与你的项目。你应该记录如何运行所有构建的步骤。如果你引用另一个项目，或者一个概念，要创建对应链接。如果你引用任何可链接的东西，链接到它。

要彻底完成文档工作，这会使你的项目有很大的不同。

写测试

为什么要测试:

• 它将建立你对系统健康的信心

• 将使您自信地合并PRs

• 即使你离开这个项目，系统也可以正常工作

有一次我发布了一个库，没有测试，Paul Irish说，“如果它有一些测试会很酷”。我去写测试。从这些测试中发现了15个bug !

如果你做任何事情，建议都进行测试。后期会为你节省很多时间。

Repo的先决条件

你需要准备README.md、CONTRIBUTING.md、LICENSE.txt以及一个有效、完整的package.json。

你应该始终包含README 和LICENSE.txt。

CONTRIBUTING.md不仅可以指定如何处理项目，还可以链接到/添加您的代码标准。添加代码标准，有助于参与项目和贡献代码。

加分项

当你写了很棒的文档，API很棒，所有的预发布项目都准备好了。等等我还有一些意见。

徽章。没有什么比徽章更能让你的repo看起来合法。太多的徽章看起来很烂，但如果你有一些有用的徽章，它就是合法性的标志。它可以显示有用的信息，诸如npm的版本,测试状态,覆盖率数据。

此外，Markdown支持原始HTML，因此您可以使repo头看起来更漂亮。中间加上一句引文，让它变得活泼一点。

还可以在这里添加一个类似的贡献者条目：
https://github.com/kentcdodds/all贡献者。这是一种很好的方式来认识那些为这个项目做出贡献的人。

发布与营销

你怎么能让人们真正去查看并使用你的新库?

我的建议非常具体。在美国东部时间星期一下午12点发行。这是Europes day的结束，纽约的午餐休息时间，以及在任何事情发生之前的旧金山早上的时间。你有很大一部分目标观众在互联网上玩弄着拇指！

至于如何发布，我认为Twitter是第一站。这个过程大概如此：

浏览Twitter

哦！看这个微博！

哦？这个东西做什么! ?

点击链接REPO,

哦！看起来酷！

复制/粘贴到终端,

开始摇滚吧！

根据你的粉丝数量和他们对你所推广的任何技术偏好，你的里程可能会有所不同，但这通常是有效的。除了Twitter，还有HN(不好意思)和Reddit。

另外，如果你的想法很棒，那就在你发布软件的时候附上一篇博客文章，尤其以公司名义发布，你可以用更长的文章来展示。要大胆！要自信！

维护

我很害怕进入这一段，但我很高兴地告诉大家，我从失败中学到了什么，希望你们能读懂。

你发布了开源库。它有两种结局：

• 以失败告终

谁在乎，我总是这样。有时一些东西不会火， 这并不意味着你的想法错误。 重要的是你做了一些事情。

• 大受欢迎

如果有人对你的项目感兴趣，让他们成为一个维护者。因为新的技术会不断出现，随之出现很多新的问题。

接下来，我想谈谈与人打交道。这是一个开源的最大的问题,很多时候比编写代码更重要。人们会跟你说很多废话，因为人们有权利公开地谈论你的项目。

我花了很多时间为一些事情争吵，但是并不是所有提意见的都是恶意。想想看，你面向全世界去开放项目，很多人并不使用英语。想象一下，你想为一个用俄语写的项目做贡献。但是你不懂俄语。所以用谷歌去翻译“什么时候完成?”成俄语，乍一看，俄语的意思可能会变成说：“嘿，这家伙的问题到底是什么”。所以，为了避免沟通的问题，建议设定一些基本规则：

• 要求复制案例或失败的测试用例。

• 详细描述发生错误的前提条件

如果你没有时间去找出一个错误，那么让用户向你证明这个bug的存在，并详细描述，以便你可以花时间修复它。

特别重要的，建议你“语义化的版本控制”， 你所能做的就是让语义化的版本控制为你提供一个健全的方式来发行以及升级套件，而无需推出新的相依套件，节省你的时间及烦恼。

结论

我希望能帮助那些想要发布自己的开源软件的人，并为他们节省一些时间和精力。

我还有最后一个建议。除非你真的想做，否则不要去做。不要觉得你必须这么做。没有它你也能找到工作。没有它，你可以成为一个优秀的开发人员。我从中学到了很多，也很喜欢这样做，但是我再也没有时间去做那些我在图书馆里做的事了，还有那些我可以和家人一起做的事，或者追求自己的爱好，或者做任何可以提供收入的事情。因为你想做就去做。如果你对你正在创造的项目没有热情，它可能不会成功。

原文链接：

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

译者介绍：

杨大江，目前担任优铭云计算公司的培训部门经理，职业生涯始于大学时候兼职数据库开发，为学校开发图书馆管理系统，和参加某公司开发后端金融系统。 在IT领域工作超过20年，发表过多篇论文。参加了数个大型云计算项目和网络安全项目，同时在培训和项目管理方面拥有丰富的经验。现在也在进行区块链技术的研究和项目实践。