如何做一个真正牛X的开源项目

jopen 11年前

  近年来,越来越多的开发者选择将自己的产品以开源形式发布,有时的结果是——你满怀诚意地开源,却无人问津。尽管你的产品做得相当好,但是仅把产品的源代码公布出来,这还不算开源,因为其他用户可能无从下手。没有用户,久而久之,你的满腔热情就会熄灭。 

  那么如何才能让开源项目为更多人所知,成为一个真正牛X的开源项目呢?除了项目自身优秀外,你还需要注意以下事项。 

  一、有一个真正有用的 README 

  即使你为你的开源项目制作了一个很好的网站,但是一些潜在用户很可能会首先通过阅读 README 文件来了解这个项目。因此,你要确保在 README 中提供尽可能全面的信息: 

  1.   依赖、安装信息 

  尽可能写清楚依赖、安装信息,最好能够让用户通过复制粘贴相关代码来添加依赖。比如这样。 

  2. 项目成熟度状态 

  不至于让用户在生产环境中用了几个月后才发现你的项目才处于 Alpha 阶段。 

  3.   详细说明项目支持的语言、运行环境和工具的版本 

  不至于让用户花费大量的时间去摸索你的项目的兼容性。 

  4.   明确所使用的许可证 

  这个许可证需要是流行的、用户都知道的,如果你自己创造一个或使用一个陌生的(比如 WTFPL),那么没有用户敢于在自己的产品中使用你的开源项目的。你可以选择比较友好的 Apache Public License 2.0Eclipse Public License 等。需要注意的是一些许可证(比如 MIT)也是比较流行的,但是没有提供任何专利保护。你也可以采用 APL2/GPLv2 双许可,让用户挑选适合他们的。 

  二、为你的项目写一个文档 

  写文档并不容易,且比较费时,但是对于用户来说,文档是了解一个项目最便捷、最省时的方式,还可以让用户相信你不会轻易放弃这个项目。 

  在文档中,把你的项目可以帮助用户完成的事情放在首位,这是用户决定是否使用这个项目的关键。此外,你要让用户相信做这个项目的是个人,而不是一个会产生代码的机器人。 

  三、项目可以很容易地升级 

  随着项目中 bug 的修复和一些功能的改进,你需要发布另一个版本。需要注意的是: 

  1.   向后兼容 

  不要因为不向后兼容,而让用户重写大量代码。这样会让用户愤怒,继而抛弃你的项目。当然,你也不必像 OpenJDK 那样兼容 15 年前的产品。 

  2.   更新日志 

  有一个清晰明确的更新日志,需要包含:该版本发生了什么变化?会破坏用户现有项目的代码吗?等等。比如 推ter 的做法: 

  • 每修复一个 bug,就在更新日志中写上一个简短的条目
  • 每添加一个功能,就简要描述一下并附上一些示例代码
  • 每改变一个 API,就需要在日志中用粗体明确指出

如果你有多个分支,就需要为每个分支都写一份更新日志。 

  3.   版本标签 

  为你的项目的每一个版本打上一个标签,比如 v1.0.0-alpha1、v1.0.0、v1.1.2,可以让你的用户很清晰地分辨出项目的版本。 

  4.   发布公告 

  项目发布后,接下来就需要为这个事件写一篇博文,或直接将公告发布到项目的邮件列表中。 

  在公告中需要说明这个项目有什么用,是否向后兼容,并给出更新日志的链接。 

  5.   项目状态标签 

  有些项目很长时间一直使用相同的版本号,比如 1.1.0,而项目一直在改进。如果这是一个开发版本,你也需要通过标签来说明项目所处的开发阶段。比如: 

  • 1. 1.0.pre1
  • 1. 1.0-alpha1
  • 1. 1.0-SNAPSHOT

总之,你要确保项目有一个严格的版本命名规划。 

  四、使用 GitHub 

  在 GitHub 上,你可以很容易地做下面的事情: 

  • 发布你的项目
  • 浏览和搜索代码
  • 专注于项目 issues
  • 参与贡献,合并用户的贡献

  五、确保有一个为用户提供支持的地方 

  如果你的项目达到一定的普及程度,你就会不断收到用户的提问。你需要有一个收集和回答用户提问的地方,比如论坛、邮件列表等。只要有一个交流的地方,用户也可以彼此提供帮助。久而久之,就会形成一个很不错的社区。 

  六、项目传递 

  不排除这种情况——你可能会对项目维护失去兴趣,或者你换了一个新工作不再使用当前的项目了。你可以在邮件列表上公布,让其他开发者接管你的项目。在 Github 上项目所有权转移会更容易,尤其是在别人为你的项目引入了新功能后。 

  无论如何,不要让项目死掉。 

  七、总结 

  总之,在你打算发布开源产品时,请确保它有: 

  • 清晰的依赖/安装说明
  • 至少有一个简短的文档/指南
  • 库中包含更改日志和相关标签
  • 一些关于支持语言、运行环境、工具版本、项目成熟度的信息
  • 邮件列表,供用户提问、相互帮助

  八、最后 

  总之,要想让你的开源项目“发扬光大”,首先应该让它对用户更友好。除了项目文档外,其他事情花费不了多长时间。 

  另外,将项目开源出来容易,长时间维护就难了,因此,你还需要具备坚毅的精神和打持久战的准备。当然,如果你只希望将项目开源出来,而不指望它能够发展得多好,那么你完全可以忽略以上的所有内容。  

英文原文:How to Make Your Open Source Project Really Awesome

来自: www.iteye.com