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

若是你想发布一个开源库，请确保它有如下特色：

• 清晰的依赖性和安装说明
• 至少有一个简要的文档指南
• 修改日志和仓库中的标签
• 关于支持的语言、运行时、工具版本的信息和项目的成熟度
• 一个可让用户提问和交流的邮件列表

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

怎样让你的开源项目更棒

每一年，愈来愈多的人发布了本身开发的库而且它们开源。这里咱们分享一些咱们经验，以便你的用户对你的库满意。

这里有一个经验法则：

不要让你的用户生气！

也能够理解为：

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

如今让咱们经过一些努力来实现这个目标。

建立一个实用的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上工做将近两年后，我能够自信地说，咱们的用户最感谢咱们的就是咱们写的项目文档：

• [Elastisch documentation]
• [Welle documentation]
• [Neocons documentation]
• [Monger documentation]
• [Langohr documentation]

写出优秀的文档须要花些时间。幸运的是，现代工具能够帮到你而且大大减小你必须解决的一些烦人的事。

咱们为ClojureWerkz项目开源了咱们的 基于Jekyll的文档模板 。咱们在CSS和设计中视觉效果方面不是很擅长，因此咱们使用了Twitter的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中清楚地说明能够得到帮助的途径。

在Twitter上常常搜你项目的名字，你就会发现各类各样的问题，批评和表扬的。若是你频繁地使用Twitter，为你的项目建立一个独立的账号，就像咱们的@ClojureWerkz。

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

若是你须要一个例子，Welle README有一节关于社区和支持的。

怎么把它搞糟

若是你想彻底坑你的用户，试试下面：

• 关闭你Github上问题的功能
• 用开发协议，那么用户必须写纸质信到坦桑尼亚
• 即便在README中修改了一行也要使用补丁
• 把你的项目放到Darcs，即便它是Ruby、JavaScirpt或者Clojure的项目
• 让人们很难找到项目在哪儿

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

传给别人

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

无论你作什么，不要让你的项目变成没人负责的项目。这是最确信的方式可让你如今或者将来的用户能够继续小猫大屠杀。

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

怎么把它搞糟

若是你想彻底坑你的用户，试试下面：

• 没有解释地直接中止贡献代码，回答邮件列表的问题
• 忽略提交请求，说他们的提交没有用，应该提交其它
• 说你是一个一旦问题解决就没有任何兴趣的人

这样就能够确保你的项目最后会被复制至少300次，最后一个代替的项目会被建立，由于搞清楚那个复制项目解决了那个问题是很烦人的。

最后的思考

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

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

若是你不想作一些很酷的事情，可能不要在第一时间就发布它。

---

原文：How to Make Your Open Source Project Really Awesome
转载自：伯乐在线 - archychu