-
做一个优秀的开源项目,需要注意哪些方面?
2017-06-03 15:20:00修改日志和仓库中的标签 关于支持的语言、运行时、工具版本的信息和项目的成熟度 一个可以让用户提问和交流的邮件列表 缺少任何一项都会造成一些用户的愤怒和沮丧,当然同时也浪费了时间。 怎样让你的开源项目更棒 ...摘要
如果你想发布一个开源库,请确保它有以下特点:
清晰的依赖性和安装说明
至少有一个简要的文档指南
修改日志和仓库中的标签
关于支持的语言、运行时、工具版本的信息和项目的成熟度
一个可以让用户提问和交流的邮件列表
缺少任何一项都会造成一些用户的愤怒和沮丧,当然同时也浪费了时间。
怎样让你的开源项目更棒
每年,越来越多的人发布了自己开发的库并且它们开源。这里我们分享一些我们经验,以便你的用户对你的库满意。
这里有一个经验法则:
不要让你的用户生气!
也可以理解为:
不要让你的用户有想要砸电脑的冲动
现在让我们通过一些努力来实现这个目标。
创建一个实用的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还在测试的时候就已经在使用它了,而且几乎可以说没有其它什么事情让我有更多的专业机会。我很高兴我能有今天而不是活跃在开源社区。
如果你不想做一些很酷的事情,可能不要在第一时间就发布它。
原文链接: ClojureWerkz 翻译: 伯乐在线 - archychu
文章转载自 开源中国社区 [http://www.oschina.net]
-
MongoDB分片键的选择和案例实例详解
2020-12-16 05:19:19下决定时一定要严肃,一旦选择了分片键,就必须坚持选择,分片键是不可以修改的。要让分片键提供好的体验,部分源自了解怎样才算一个好的分片键。 本文将详细介绍关于MongoDB分片键的选择和案例,分享出来供大家参考... -
专家门诊 Visual C++开发答疑300问 pdf书(含全部代码)
2009-11-16 22:20:23如何获得和修改目录的日期和时间 第14章 数学算法 中文和英文字符所占的字节数是一样的吗 如何统计一段中英文混合字符的字符数 排序法都有哪些,其算法都是怎样的 如何将十进制字符串、十六进制字符串和二进制字符... -
测试培训教材
2014-04-01 12:10:48需要“Launching Quick Test Professional”来进一步地编辑和修改自动化测试脚本。 什么是BPT? 业务组件测试 用户参与、尽早测试: 基于角色和工作流的BPT模型 角色定义应该灵活、根据能力、时间资源等... -
外贸专家永久注册版.exe
2018-12-25 15:36:19您公司的某个商品要卖给不同的客户,而客户有时会提供他自己的相应货号,报价或做出口合同时,怎样找到该客户对应的的货号呢,传统的方法是把以前所有有关该客户的报价,订单统统找一遍。《外贸专家》为您解决了这... -
word使用技巧大全
2011-03-18 20:37:53★怎样创建自己的电子邮件签名或电子邮件信 32 ★怎样用Word在网上开会 33 ★给会议来点Web讨论 33 ★用剪贴板的内容进行替换 33 ★十进制字符与Unicode字符的转换 34 ★巧用“修订”功能帮朋友修改文章 34 ★利用... -
Tc2.0 编写俄罗斯方块游戏
2010-06-11 20:07:46怎样修改游戏板的状态? 怎样统计分数? 怎样处理升级后的加速问题? 怎样判断游戏结束? 关于计分板设计的问题。 关于“下一个”形状取法的问题。 剩下的问题。 *****************************************... -
VB编程资源大全(源码 网络)
2007-10-17 22:54:271,codenet5.ZIP 网络五子棋(84KB) 2,mailcheck.ZIP 邮件检查程序(8KB) 3,sendmail.ZIP 简单电子邮件发送程序(4KB) 4,whois.ZIP Whois 示例程序(2KB) 5,mailsender_plus.ZIP 发送... -
C#开发典型模块大全
2014-03-12 18:11:224.2.4 怎样操作RichtextBox控件的选择文本 82 4.2.5 如何获取数据表中字段的描述信息 83 4.3 设计过程 83 4.3.1 获取数据表中字段的中文信息 84 4.3.2 添加数据表的查询条件 86 4.3.3 向SQL语句中添加... -
C#程序开发范例宝典电子书从1-471例后面的暂时没有
2008-10-16 21:15:36实例104 使用Timer组件显示当前系统时间 150 实例105 使用Timer组件制作左右飘动的窗体 151 实例106 使用Timer组件实现奥运倒计时 152 3.8 ServiceController组件 154 实例107 使用ServiceController组件... -
软件工程师典藏:C#程序开发范例宝典(第2版).part01
2012-11-11 20:05:51实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例268 程序运行时禁止关机 364 实例269 获取任务栏尺寸大小 365 实例270 改变系统提示信息... -
C#程序开发范例宝典(第2版).part02
2012-11-12 07:55:11一部久享盛誉的程序开发宝典。精选570个典型范例,全面覆盖实用和热点技术,涉及面...实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例... -
C#程序开发范例宝典(第2版).part13
2012-11-12 20:17:14一部久享盛誉的程序开发宝典。精选570个典型范例,全面覆盖实用和热点技术,涉及面...实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例... -
C#程序开发范例宝典(第2版).part08
2012-11-12 08:04:21一部久享盛誉的程序开发宝典。精选570个典型范例,全面覆盖实用和热点技术,涉及面...实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例... -
C#程序开发范例宝典(第2版).part03
2012-11-12 07:56:38一部久享盛誉的程序开发宝典。精选570个典型范例,全面覆盖实用和热点技术,涉及面...实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例... -
程序开发范例宝典>>
2012-10-24 10:41:28实例112 使用Timer组件显示当前系统时间 165 实例113 使用Timer组件制作左右飘动的窗体 166 实例114 使用Timer组件实现奥运倒计时 167 3.8 ServiceController组件 169 实例115 使用ServiceController... -
书 名:程序开发范例宝典>>【中卷】(分三卷上传完本书案例)
2010-04-05 21:59:37实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例268 程序运行时禁止关机 364 实例269 获取任务栏尺寸大小 365 实例270 ... -
书 名:程序开发范例宝典>>【下卷】(分三卷上传完本书案例)
2010-04-05 03:24:09实例265 怎样调用外部的EXE文件 361 实例266 关闭外部已开启的程序 362 7.10 程序运行 363 实例267 防止程序多次运行 363 实例268 程序运行时禁止关机 364 实例269 获取任务栏尺寸大小 365 实例270 ... -
Delphi开发范例宝典目录
2014-03-07 10:24:25实例272 和服务器时间同步 350 实例273 取得网络中的SQL服务器名 351 8.5 数据库维护 352 实例274 数据库登录配置 352 实例275 SQL Server数据库的备份和恢复 353 实实276 数据库附加、分离 355 实例277... -
C#.net_经典编程例子400个
2013-05-17 09:25:30142 3.6 Process组件 143 实例102 使用Process组件访问本地进程 143 3.7 Timer组件 145 实例103 使用Timer组件制作计时器 145 实例104 使用Timer组件显示当前系统时间 150 实例105 ... -
RFC中文文档-txt
2009-09-11 14:56:56RFC1635 怎样使用匿名FTP RFC1636 IAB工厂关于在Internet体系结构的安全报告 -2月8-10号, 1994 RFC1643 以太网-类似界面类型的管理对象的定义 RFC1658 字符流设备使用SMIv2管理对象的定义 RFC1661 点对点协议(PPP) ... -
中文版RFC,共456
2009-04-19 22:56:29RFC1635 怎样使用匿名FTP RFC1636 IAB工厂关于在Internet体系结构的安全报告 -2月8-10号, 1994 RFC1643 以太网-类似界面类型的管理对象的定义 RFC1658 字符流设备使用SMIv2管理对象的定义 RFC1661 点对点协议(PPP) ... -
rfc中文文档目录,包含部分翻译
2009-07-22 21:34:18RFC1635_怎样使用匿名FTP RFC1636 IAB工厂关于在Internet体系结构的安全报告 -2月8-10号, 1994 RFC1643 以太网-类似界面类型的管理对象的定义 RFC1658 字符流设备使用SMIv2管理对象的定义 RFC1661_点对点协议(PPP... -
网络爸爸破解文件.rar
2009-11-21 17:59:39自从网络爸爸7.0.6.10版本被人破解之后,以往的杀进程法(如冰刃IceSword,MagicHide)、强行卸载法(如完美卸载)、DOS删除目录法、安全模式修改注册表法、万能密码法(如lenovo)、修改系统时间法……统统失效!... -
HTML开发王
2013-01-03 11:33:097.3.7 链接到电子邮件地址 7.3.8 链接到任何类型的文件以供下载 7.3.9 创建空链接和脚本链接 7.3.10 链接的创建与管理 7.4 定义书签和链接到书签 7.4.1 定义命名锚点(id属性和name属性) 7.4.2 链接到命名锚点 7.5 ... -
[HTML开发王].张亚飞.扫描版
2011-09-13 12:45:047.3.7 链接到电子邮件地址 7.3.8 链接到任何类型的文件以供下载 7.3.9 创建空链接和脚本链接 7.3.10 链接的创建与管理 7.4 定义书签和链接到书签 7.4.1 定义命名锚点(id属性和name属性) 7.4.2 链接到命名锚点 7.5 ... -
计算机网络与因特网(互联网技术的“圣经”)
2011-07-13 00:32:04对全书做了很多修改和更新。本书是描述互联网技术的经典之作,被认为是互联网技术的“圣经”。 目 录 译者序 前言 第1章 导论 …1 1.1 计算机网络的发展 1 1.2 网络系统复杂性 1 1.3 对复杂性的控制 2 1.4 概念与... -
flash shiti
2014-03-14 10:32:415. 编辑位图图像时,修改的是: □ A. 像素 □ B. 曲线 □ C. 直线 □ D. 网格 6. 单击View>Hide Edges 的作用是: □ A. 隐藏被选择对象的突出显示状态 □ B. 隐藏被选择对象的外框轮廓 □ C. 隐藏被选择对象的填充... -
C#程序开发范例宝典
2010-12-15 20:05:16实例104 使用Timer组件显示当前系统时间...... 150 实例105 使用Timer组件制作左右飘动的窗体...... 151 实例106 使用Timer组件实现奥运倒计时...... 152 3.8 ServiceController组件...... 154 实例107 ... -
一步步学会使用PHP基础,学会使用ThinkPHP5进行基础实战开发
2018-06-27 23:05:42所有讲解默认隐藏入口文件和开启PHTHINFO模式,隐藏入口文件等请参考官方相关文档,当然我也会在第一章先看到页面里说明怎样操作; 前端使用bootstrap3; 使用最新核心版的TP5; 已更新内容列表 前言 2017-02-11 1.1...
-
Redis为什么这么快
-
glide-4.0.0.7z
-
MySQL 高可用工具 DRBD 实战部署详解
-
linux基础入门和项目实战部署系列课程
-
培训效果评价方法.pdf
-
mysql数据库-多表查询
-
Linux基础入门系列课程
-
JMETER 性能测试基础课程
-
基于python的dango框架购物商城毕业设计毕设源代码使用教程
-
【Python-随到随学】 FLask第一周
-
C#编译错误:CS1056 意外字符 ‘‘
-
Lazarus 2021年最新版下载
-
Linux 上安装配置 VNC Server
-
MySQL你该了解的那些事【服务端篇】
-
Industry-Dropdown-Cookie:这会检查URL并根据用户是否进入Thankyou URL来设置cookie,因此删除了selectelement,该selectelement阻止用户无需选择元素即可继续进行结帐,从而避免了多次选择-源码
-
半股票调和:我只提出了几个主题,外加一些摘要和其他调整-源码
-
RapidScada从入门到精通
-
MySQL 主从复制 Replication 详解(Linux 和 W
-
单片机技术应用实训装置
-
一次清理k8s集群中异常状态pod