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

jopen 12年前

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

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

　　一、有一个真正有用的 README 

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

　　1.   依赖、安装信息 

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

　　2. 项目成熟度状态 

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

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

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

　　4.   明确所使用的许可证 

　　这个许可证需要是流行的、用户都知道的，如果你自己创造一个或使用一个陌生的（比如 WTFPL），那么没有用户敢于在自己的产品中使用你的开源项目的。你可以选择比较友好的 Apache Public License 2.0或 Eclipse 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