做一个优秀的开源项目，需要注意哪些方面？

jopen 11年前

摘要

如果你想发布一个开源库，请确保它有以下特点：

  • 清晰的依赖性和安装说明

  • 至少有一个简要的文档指南

  • 修改日志和仓库中的标签

  • 关于支持的语言、运行时、工具版本的信息和项目的成熟度

  • 一个可以让用户提问和交流的邮件列表

缺少任何一项都会造成一些用户的愤怒和沮丧，当然同时也浪费了时间。

怎样让你的开源项目更棒

每年，越来越多的人发布了自己开发的库并且它们开源。这里我们分享一些我们经验，以便你的用户对你的库满意。

这里有一个经验法则：

不要让你的用户生气！

也可以理解为：

不要让你的用户有想要砸电脑的冲动

现在让我们通过一些努力来实现这个目标。

创建一个实用的README

即使你的项目有一个很棒的网站，潜在的用户第一次接触这个项目很可能就是通过阅读README文件。我们需要确保它很棒并且包含了有用的信息。

提供依赖信息

那么说你会发布你的开源项目。这说明你很聪明，真有你的！不幸的是，不是所有人都像你那样，而且有一些人对这门语言或者你在做的系统完全不了解。这意味着对你来说很显然的事情对他们来说就一点也不显然了。

其中一件就是缺少依赖说明或者安装说明

我到底怎么安装这个东西，难道不能说得清楚一些吗?

这很快就能让用户生气。在源代码里找你的包或者构件的名字是很烦人的，有些项目对构件使用一些特别有才的名字，完全不符合仓库的名字。

让你的用户从这些糟糕的事情中脱离出来吧。问题是怎样添加依赖性，理想状况下可以通过复制粘贴一小段代码。

如果需要例子的话可以点击 Welle。

清楚的说明项目的成熟度

你在生产中使用这个项目有几个月了吗？你是否觉得它还是不完整的？你是否希望API在下一个版本会彻底地修改？你的项目是否在要求最多并且很老的项目中也能稳定安全的使用？

要把这些说得清楚。下次你就不会因为做了一个错误的介绍，但是没有的提供任何项目成熟度的信息而项目浪费一周的时间了。你会意识到几句短短的话就能产生很大的影响。

运行时、语言、工具版本的文档支持

当考虑到向后兼容时，Clojure有一个很好的跟踪记录。它好的几乎让人难以置信。包括1.2到1.3的升级，之后的升级对绝大多数的项目来说就是一个简单替换。同样地，那些高于1.2的项目大多使用了最新的稳定版本。

然而，不会一直都是这样。在某些情况下，未来版本的Clojure会打破兼容性。我们怎么让我们的用户不愤怒？通过在README中清楚的说明哪些版本是支持的。

这只需要写一行文字。这样，在你发布的那一周就少了抱怨，同时也减少了初学者的很多麻烦。

如果你需要一个例子，有一个来自 Welle的例子。

说明你使用了什么许可证

你可能并不太关心许可证，但是那些在大公司中想用你的库的人很关心。他们必须知道！当他们想用Clojure/Node.js/Scala/Go等等的时候，可能不能使用。

因此清楚的说明你的许可证。也请你使用一些对商业友好的协议，除非你有自己的理由。（ Apache Public License 2.0和Eclipse Public License）是不错的选择。注意到一些许可证(比如MIT)的确很友好、流行，但是不提供任何专利保护，在当前的法律环境下也不应该忽视。

最后，记得你可以使用双许可证，如果你真的是许可证中立的话可以使用，比如APL2/GPLv2。那个你的用户就可以选择最适合他们的许可证了。

疑惑的时候，可以参考摘要：合法、开源许可证用白话概括（但是别把它当作合法的建议）

怎么把它搞糟

如果你想坑你的用户，可以试试：

  • 在你项目的根目录放一个空的README

  • 在末尾写上“欢迎加补丁”

  • 发明你自己的许可证或者使用一个完全不熟悉的，比如WTFPL

那么你的项目就永远不会有用户了。我保证。

为你的项目写文档

写文档不容易同时也是需要花费一些时间的。然而，文档是你能为你的用户做的最好的事了。不仅能够节省他们大量的时间，也可以让他们确信你的库不是被遗弃的软件。

文档能够让你的用户完成他们起初使用你的库的任务。像Rob Pike说的，它“让这些任务成为可能”。这让你的用户知道你重视这一点，让他们知道你是个有血有肉的人，不是一个产生代码的机器。

在ClojureWerkz上工作将近两年后，我可以自信地说，我们的用户最感谢我们的就是我们写的项目文档：

写出优秀的文档需要花些时间。幸运的是，现代工具可以帮到你并且大大减少你必须解决的一些烦人的事。

我们为ClojureWerkz项目开源了我们的基于Jekyll的文档模板。我们在CSS和设计中视觉效果方面不是很擅长，所以我们使用了推ter的BootStrap库。我们的文档站点可以更好看，但是相比大多数开源项目来说已经很不错了。你可以使用我们的模板或者为你的项目开发类似的工具。

更好的是，如果你开源了你的文档站点(这似乎没有理由不那么做)，你会看到人们会比贡献代码的修改更早的贡献出小的改进。

如果你仍然不确定是否值得为你的项目写文档，看一下 Jacob Kaplan-Moss的这个报告：

怎么把它搞糟

如果你想坑你的用户，可以试试：

  • 不要写一个文档说明，甚至连例子也不写

  • 确保你的API说明已经有三个月没有更新了

  • 声明那些不愿意读代码去理解即使是最基本的东西的用户是愚蠢的，并且应该去卖汉堡！

更容易升级

某些时候，你想要发行项目的另一个版本。这可能是让你的用户很开心，因为他们已经使用了你的库，或者很生气，浪费了他们时间。

不关心向后兼容

关于软件开发的一件很令人生气的事就是当你升级一个库但是数百个测试失败了。更让我生气的就是我还要重写我一半的基础代码，因为有人在没有任何警告的前提下决定打破公共的API。

因此，致力于维护向后兼容性。当然你没有必要像OpenJDK那样支持15年以前的项目。但是在移除之前建议不使用一些东西能够更容易发现哪些地方改动了。

你怎么做到这点呢？维护一个修改日志。

拥有一个修改日志

有时，你的用户会升级（关于这一点在下文会更多的介绍）。他们会问自己一个问题：

这次发布改动了什么地方呢？

然后

我的代码会不能用吗？我是不是一定要重写？

最后

Joe，那个运维的家伙会因为我升级讨厌我吗？

所有这些问题都能通过一个修改日志得到解答。它像推特一样只不过它真的很实用，它是这样用的：

  • 每次你解决一个bug，在日志里加一个简单的记录

  • 每次你加入一个新特性，在日志里简单地提一下，并且用几个代码例子解释它。

  • 每次你做了重大的API改动，在日志中用粗体清楚的说明

就是这些了。没有第三步！

修改日志一般把最新的记录放在最前面。改动是按版本分类的。如果你有多个分支(比如master和1.0.x)，每一个都应该有一个独立的修改日志。

就是这些了。可以看看， Welle的修改日志

给版本加上标签

又是那个时候了，你已经升级版本并且马上就要发布构件了。停一停，先做一件事：给这次提交加上标签。没有标签的话，找两个版本之间的不同会很痛苦的。

一些依赖性(比如Bundler, Rebar)和配置管理工具可以使用标签，开发者系统这些标签是可用的。

使用统一的版本信息，比如v1.0.0-alpha1, v1.0.0, v1.1.2等。标签不一致绝对会导致运维的人整天讨厌你的项目。

宣布版本发行

在你发布一个版本字之后就是要写一个博客日志，或者在你们项目的邮件列表或更大的相关的邮件列表中发个更新(比如Clojure邮件列表或者RabbitMQ)

确保主题是以ANN或者[ANN]开头的，这意味着这是一个通告。比如

ANN Welle 1.5.0 发布了

在你的通告中，清楚的说明你的项目是做什么的，它是否向后兼容，并且有到修改日志的链接，可以让用户找到更多的细节。就是这样了。

开发时使用预览或者快照版本

你有没有曾经看到一个项目用同一个版本，比如0.2.1将近半年？你怎么知道哪一个版本才是0.2.1呢？这是一个还在开发中的版本吗？是不是有人升级后忘了修改版本号？到底怎么回事？

这会让所有的开发者疯掉的！千万别做那样的人！在项目中用预览或者快照版本，当你快要发布一个版本的时候才揭开那个版本。然后立即升级那个版本。

举几个开发版本的例子：

  • 1.1.0.pre1

  • 1.1.0-alpha1

  • 1.1.0-SNAPSHOT

任何其他开发版本的命名格式是不清楚的，并且会你的用户很不愉快。

怎么把它搞糟

如果你想完全坑你的用户，试试下面：
* 随意打破公用的API，最好巧妙地，连你的测试也不会发现API的修改
* 忘了升级版本信息
* 从不给版本加标签
* 从不宣布版本发行

使用GitHub

我和gitHub没有友好关系，也不要假设Git是“最好”的版本控制系统。但是它真的不错。最近几乎所有人都在使用GitHub。

GitHub让下面几件事变得更简单：

  • 发现你的项目

  • 浏览和搜索代码

  • 通过填问题或者@使你能够关注问题

  • 为小的改动做出贡献

可能最重要的是，GitHub对不是技术大牛的很友好。是的，它的确是，同时他们正努力让它变得更好。

使用GitHub意味着你能尤其简单地使用CI的服务(Travis CI)。

如果你不让你的用户去处理补丁、为了提交问题在网上到处找你的email、通过糟糕的3G网络复制你300M的仓库只是为了编辑一个排版错误，你将得到更多的赞赏。

@old_sound @g3rtm bitbucket毫无疑问是很好的服务。但对于使用公开代码的人开始显得有点难了。– Michael Klishin (@michaelklishin) 21 de enero de 2013

不要把事情弄得困难。

提供一个让用户可以得到帮助的地方

如果你的项目达到了一定程度的流行度，你必须回答关于它的一些问题。为了这一点，设置一个邮件列表(一个Google群)或者如果你经常上IRC的话，开启一个通道吧。

认为你没有足够的时间？使用邮件列表最好的部分就是如果你给了一个途径，用户会互相帮助。所以在你项目的README中清楚地说明可以获得帮助的途径。

在推ter上经常搜你项目的名字，你就会发现各种各样的问题，批评和表扬的。如果你频繁地使用推ter，为你的项目创建一个独立的帐号，就像我们的@ClojureWerkz。

这可以让你创建一个社区，让你知道人们是怎么使用你的项目的、还有什么地方可以提高。最后，它会帮助你找到可以帮助你维护你项目的人。这不仅能节省你的时间，也会鼓励人们到处宣传你的项目。

如果你需要一个例子，Welle README有一节关于社区和支持的。

怎么把它搞糟

如果你想完全坑你的用户，试试下面：

  • 关闭你Github上问题的功能

  • 用开发协议，那么用户必须写纸质信到坦桑尼亚

  • 即使在README中修改了一行也要使用补丁

  • 把你的项目放到Darcs，即使它是Ruby、JavaScirpt或者Clojure的项目

  • 让人们很难找到项目在哪儿

这可以防止人们为你的项目做出贡献或者从你地方偷一点想法。

传给别人

到了一定时候，你可能对维护你的项目变得不感行却了。可能你已经换了一个新工作，或者不再使用你自己的项目了。在邮件列表中宣布这件事，让其他人来 接管这个项目。不久以后，有人会来帮忙的。在Github上对这种事是有好处的，特别是他们已经公布了一个让你转你仓库管理权的新特性。

不管你做什么，不要让你的项目变成没人负责的项目。这是最确信的方式可以让你现在或者未来的用户可以继续小猫大屠杀。

把项目移交给别人总是比之后找借口更好的。

怎么把它搞糟

如果你想完全坑你的用户，试试下面：

  • 没有解释地直接停止贡献代码，回答邮件列表的问题

  • 忽略提交请求，说他们的提交没有用，应该提交其它

  • 说你是一个一旦问题解决就没有任何兴趣的人

这样就可以确保你的项目最后会被复制至少300次，最后一个代替的项目会被创建，因为搞清楚那个复制项目解决了那个问题是很烦人的。

最后的思考

正如你看到的，让你的项目可以被接受不是那么难吧。除了文档说明，让你的用户不生气，让运维的人不讨厌你也不需要花太多的时间。

维护一个开源项目是需要时间和精力的。但是它也是有回报的。我从GitHub还在测试的时候就已经在使用它了，而且几乎可以说没有其它什么事情让我有更多的专业机会。我很高兴我能有今天而不是活跃在开源社区。

如果你不想做一些很酷的事情，可能不要在第一时间就发布它。

原文链接： ClojureWerkz   翻译： 伯乐在线 - archychu
译文链接： http://blog.jobbole.com/57767/