文档章节

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

李朝强
 李朝强
发布于 2013/06/20 14:59
字数 1613
阅读 3079
收藏 87

         近年来,越来越多的开发者选择将自己的产品以开源形式发布,有时的结果是——你满怀诚意地开源,却无人问津。尽管你的产品做得相当好,但是仅把产品的源代码公布出来,这还不算开源,因为其他用户可能无从下手。没有用户,久而久之,你的满腔热情就会熄灭。 那么如何才能让开源项目为更多人所知,成为一个真正牛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. 更新日志 有一个清晰明确的更新日志,需要包含:该版本发生了什么变化?会破坏用户现有项目的代码吗?等等。比如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上项目所有权转移会更容易,尤其是在别人为你的项目引入了新功能后。 无论如何,不要让项目死掉。

   七、总结 总之,在你打算发布开源产品时,请确保它有: 清晰的依赖/安装说明 至少有一个简短的文档/指南 库中包含更改日志和相关标签 一些关于支持语言、运行环境、工具版本、项目成熟度的信息 邮件列表,供用户提问、相互帮助 八、最后 总之,要想让你的开源项目“发扬光大”,首先应该让它对用户更友好。除了项目文档外,其他事情花费不了多长时间。 另外,将项目开源出来容易,长时间维护就难了,因此,你还需要具备坚毅的精神和打持久战的准备。当然,如果你只希望将项目开源出来,而不指望它能够发展得多好,那么你完全可以忽略以上的所有内容。

本文转载自:http://xcodebox.com/2013/04/8702.html

李朝强
粉丝 91
博文 297
码字总数 149962
作品 0
郑州
产品经理
私信 提问
加载中

评论(12)

飞一次
飞一次

引用来自“陈景峰”的评论

http://netkiller.github.io 你看看我的网站算不算X牛的项目? 我坚持了13年。

真不错
飞一次
飞一次

引用来自“chengjun583”的评论

的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦

z
zx32342342
先评论下再往下看,openjdk能兼容15年前的东西??牛逼
杨子江
杨子江

引用来自“陈景峰”的评论

http://netkiller.github.io 你看看我的网站算不算X牛的项目? 我坚持了13年。

走秀网的人 哈
黄开源中国
黄开源中国

引用来自“陈景峰”的评论

http://netkiller.github.io 你看看我的网站算不算X牛的项目? 我坚持了13年。

可以出很多本书。。太牛叉。。
温习江湖
温习江湖

引用来自“袁迪”的评论

引用来自“moxia”的评论

引用来自“陈景峰”的评论

http://netkiller.github.io 你看看我的网站算不算X牛的项目? 我坚持了13年。

nx

nx

内容很nx,页面无美感
zhcosin
zhcosin

引用来自“chengjun583”的评论

的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦

沙发迪
沙发迪

引用来自“moxia”的评论

引用来自“陈景峰”的评论

http://netkiller.github.io 你看看我的网站算不算X牛的项目? 我坚持了13年。

nx

nx
走位风骚闪着腰
走位风骚闪着腰

引用来自“陈景峰”的评论

http://netkiller.github.io 你看看我的网站算不算X牛的项目? 我坚持了13年。

nx
chengjun583
chengjun583
的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦的很不错。标题哗众取宠了,不必要。
很多开源项目的说明文档就是 那样,写的华而不实的哦
“爱装X”开源组织:“教科书级”AI知识树究竟长什么样?

作者 | Just 出品 | AI科技大本营(ID:rgznai100) 你看了很多本人工智能的入门书籍,但发现还是不能有效的将它们有效分类连接,进行结构化表达,因为知识点在你的大脑中是碎片化的,一片混乱...

ApacheCN_飞龙
06/02
0
0
如何高效利用 GitHub

正是 Github,让社会化编程成为现实。本文尝试谈谈 GitHub 的文化、技巧与影响。 Q1:GitHub 是什么 Q2:GitHub 风格 Q3: 在 GitHub,如何跟牛人学习 Q4: 享受纯粹的写作与演讲 Q5: 代码帮你...

二狗蛋
2013/03/02
12.1K
30
十年阿里资深架构师教你如何做到年薪50万的程序员(文末附送学习资料)

写在开篇 不管是开发、测试、运维,每个技术人员心里都有一个成为技术大牛的梦,毕竟“梦想总是要有的,万一实现了呢”!正是对技术梦的追求,促使我们不断地努力和提升自己。 然而“梦想是美...

bjweimengshu
2018/04/24
0
0
《从零构建前后分离 WEB 项目》 序 :开源的意义

序: 开源的意义 本系列提前首发地址 背景 从事了近4年的互联网行业,逐渐担当过团队的前端到后端的负责人,和大家一样从小白逐渐的成长起来,回首望去几年前的博客还是那么稚嫩。 回首这几年...

庄文达
2018/08/31
0
0
你懂那么多,为啥领导却说你不出活?

如果你想成为在某一个领域内的技术专家,该怎么做?有些同学表示,到一家相关技术的公司努力工作持续积累就可以了。当然,如果能找到这种理想的平台,你是非常幸运的。但什么样的平台才能叫做...

HarlanC
2018/08/31
0
0

没有更多内容

加载失败,请刷新页面

加载更多

OSChina 周二乱弹 —— 他只能用这个办法劝你注意身体了

Osc乱弹歌单(2019)请戳(这里) 【今日歌曲】 @-冰冰棒- :#今日歌曲推荐# Kodaline《High Hopes》 《High Hopes》- Kodaline 手机党少年们想听歌,请使劲儿戳(这里) @xiaoshiyue :仙女...

小小编辑
9分钟前
346
10
Spring Boot Actuator 整合 Prometheus

简介 Spring Boot 自带监控功能 Actuator,可以帮助实现对程序内部运行情况监控,比如监控状况、Bean加载情况、环境变量、日志信息、线程信息等。这一节结合 Prometheus 、Grafana 来更加直观...

程序员果果
18分钟前
3
0
Linux文件查找命令详解

对于文件查找,我们最好用的还是属于find命令了,在说find命令之前,先把另外几个查找命令介绍一下。 目录 0x01 查询命令介绍 0x02 find命令介绍 0x01 查询命令介绍 在介绍之前,首先先了解一...

无心的梦呓
18分钟前
3
0
快速掌握的测试用例优先级划分方法

怎么样的设计才能算测试用例 引自:IEEE Standard 610 (1990): A set of test inputs, execution conditions, and expected results developed for a particular objective, such as to exe......

测者陈磊
21分钟前
3
0
[mycat]Attribute value "roadNodeId,version" of type NMTOKEN must be a name token

不能逗号配两个字段的主键 primaryKey="roadNodeId,version" Caused by: io.mycat.config.util.ConfigException: org.xml.sax.SAXParseException; lineNumber: 7; columnNumber: 105; Attrib......

Danni3
27分钟前
4
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部