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

11顶
14踩

2013-04-25 17:45 by 副主编 wangguo 评论(17) 有37109人浏览

开源 github 文档

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

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

一、有一个真正有用的README

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

1. 依赖、安装信息

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

2. 项目成熟度状态

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

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

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

4. 明确所使用的许可证

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

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

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

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

关于开源项目文档，建议你阅读：开源项目文档应规避的13处“硬伤”

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

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

1. 向后兼容

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

2. 更新日志

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

每修复一个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

分享到：

11
顶

14
踩

评论共 17 条请登录后发表评论

17 楼 twtiyb 2013-05-07 17:36

差沙写道

好文，我的开源项目要借鉴。确实做一个合格的开源项目很难，尤其是在非英语系国家，想要向国际化发展更难。顺便广告一下 http://xadmin.io

这界面看起来华丽了，不过只是眼前一亮，但是想看什么东西还是挺费劲的。

16 楼 guaishou 2013-04-28 10:40

leon1509 写道

guaishou 写道

哇哈哈，看来我的开源项目算是及格了，200多页的开发手册呢~~（广告：code.google.com/p/portal-basic/）

您的开发手册就像老太太的裹脚布！新手看不明白，技术好的大部分都会，没说出你框架的主要特点。一点读后感，别介意！

不介意，任何意见都得听。你是第一个说不好的，这很重要。

15 楼 leon1509 2013-04-28 10:05

guaishou 写道

哇哈哈，看来我的开源项目算是及格了，200多页的开发手册呢~~（广告：code.google.com/p/portal-basic/）

您的开发手册就像老太太的裹脚布！新手看不明白，技术好的大部分都会，没说出你框架的主要特点。一点读后感，别介意！

14 楼 PetriNet 2013-04-27 19:58

房贷，孩子，养老，压得直不起腰，哪有这闲工夫，扯

13 楼 guaishou 2013-04-27 11:00

geminiyellow 写道

guaishou 写道

哇哈哈，看来我的开源项目算是及格了，200多页的开发手册呢~~（广告：code.google.com/p/portal-basic/）

有没有计划port到git上去呀，总觉得google code看起来不舒服。

刚好相反，我觉得google上最省事，下载一个文件就什么都全了，github不知是我不会用还是怎样，只能下载源代码。难道想用一个东西还要自己编译、打包？

12 楼 SpringLin 2013-04-27 10:18

感觉提议不错, 需要注意的地方还挺多的

11 楼 geminiyellow 2013-04-26 23:43

guaishou 写道

哇哈哈，看来我的开源项目算是及格了，200多页的开发手册呢~~（广告：code.google.com/p/portal-basic/）

有没有计划port到git上去呀，总觉得google code看起来不舒服。

10 楼 guaishou 2013-04-26 21:54

哇哈哈，看来我的开源项目算是及格了，200多页的开发手册呢~~（广告：code.google.com/p/portal-basic/）

9 楼 phlsbg 2013-04-26 20:14

xxg2810 写道

这是老外写给老外看的，中国哪个程序员有功夫做开源项目？有点时间睡睡觉，别加班就不错了

还在加班。。

8 楼 xxg2810 2013-04-26 16:28

这是老外写给老外看的，中国哪个程序员有功夫做开源项目？有点时间睡睡觉，别加班就不错了

7 楼 McYeah 2013-04-26 14:00

随便看下而已，还没有开发开源项目的实力...

6 楼 afuer 2013-04-26 11:23

的确不错。开源项目，只有代码是不够的。不能很好的坚持也是不行的。

5 楼差沙 2013-04-26 11:14

好文，我的开源项目要借鉴。确实做一个合格的开源项目很难，尤其是在非英语系国家，想要向国际化发展更难。顺便广告一下 http://xadmin.io

4 楼 weng 2013-04-26 10:36

geminiyellow 写道

好苦逼，又要给你看，又要给你做科普。

3 楼 geminiyellow 2013-04-26 09:45

好苦逼，又要给你看，又要给你做科普。

2 楼 minimu 2013-04-26 09:33

这些其实都不是核心的东西，纯技术人员写的东西。技术和项目，距离也许是咫尺，也许是天涯

1 楼 kukuzidian 2013-04-26 08:48

国内很多开源项目只有源码，没有项目相关的设计文档、或者文档没有及时更新。
文章写的太棒。。。。。。支持。。

发表评论

您还没有登录,请您登录后再发表评论

11顶14踩