如何贡献:详细列出贡献的规则。如果你需要人进行单元测试,那么写上去。如果你需要人编写文档,那么也写上去。给出一个检查表,这样大家在提交贡献之前可以先逐项检查一下。
在与贡献者们的交流基础上,同时也参考了其它人问的一些问题,我花了许多时间来完善CSS Lint的开发者指南。我认为,开发者指南与其它文档一样,应当是一个活跃的文档,它应当随着项目的成长而不断成长。
邮件列表的使用
所有的开源项目都会给出一个地方,让大家提问。简单的方法是设置一个邮件列表。当我们刚启动CSS Lint时,Nicole和我很快被各种问题淹没了。比较麻烦的是,这些问题来自各种渠道。有些人在Twitter上问,有些人直接给我俩写信。你不会想要面对这种局面吧。
利用Yahoo Groups和Google Groups设置邮件列表很容易,而且免费。在宣布项目上线之前,记得先设好邮件列表吧,然后主动鼓励大家用邮件列表来提问。不要忘了在你的网站上和文档里放上邮件列表的链接。
运营邮件列表的另外一个重要环节是对其进行积极地关注。对于用户或开发者来说,没有什么比自己被忽略更加令人沮丧了。如果你设置了一个邮件列表,花一些时间关注它,并 为那些提问的人作出答复。这是围绕一个项目培育出开发者社区的佳手段。让一个邮件列表达到像样的活跃度是一件比较费时的事,然而这是值得的。为有意向作出贡献的人提供建议、建议人们在适当的时候提交成果(不要让你的邮件列表变成bug追踪工具!)、并且利用你从邮件列表中获得的反馈来提升文档的质量。
使用版本号
开放源代码项目的一个常见的错误是忽视使用版本号。版本号对项目的长期稳定和维护时相当重要的。CSS Lint首次发布时没时使用版本号,我很快意识到错误。当有bug提交时,我不知道人们是否正在使用新的版本,因为没有办法告诉用户代码是何时发布的,虽然提交的bug已经修复但用户无从知晓。
将每个发布的版本用官方的版本号来标记,当有人提交bug时,你可以询问他们使用的版本并检查bug是否已经修补。这大大缩短了我花在报告bug 上的时间因为我可以马上知道用户是否在使用新版本。
除非你的项目以前有过使用并已经通过审核, 否则以0.1.0位启动版本号并递增每个后续发布的版本。在 With CSS Lint中我们增加了第二个数字在作为计划版本号,因此,0.2.0便是第二个计划版本号,0.3.0是第三个以此类推。如果我们为了修补bug而需要发布一个介于两个计划版本之间的版本,我们需要增加第三个数字。因此在第二个计划版本0.2.0之后的非计划释出本版号为0.2.2.
不要误解。这里并没有什么规则来规定在一个项目中如何增加版本号,尽管这里有些值得参考的东西 Apache APR Versioning and Semantic Versioning. 我只是挑出来一些并遵循罢了。
除了对项目跟踪的帮助,版本号当然还可以为你的项目做一些其他的事情。
源码控制中的标记版本
当你决定要发布一个新版本时,应用源码控制标记来标注此版本的代码状态。当我们开始在CSS Lint中使用版本号,我也开始这么做了。开始我没考虑那么多,直到有一次我忘了给一个发布版添加标记,但是发现某位开发者提交的bug却是针对那个特定标记的。这说明开发者们更倾向于检出特定版本的代码。
要让标记和版本号的绑定关系更明确,把版本号直接包含在标记名称中。在CSS Lint中,我们的标记都使用“v0.9.9”这种格式。这样可以让每个人都能够很容易地通过标记名称来识别其含义 — 包括你自己,因为你也将能够更好地跟踪每次版本发布的改动。
变更日志
版本管理还有一个好处是能够生成变更日志。不管是对终用户和贡献者,变更日志都是沟通版本差异时的重要依据。版本标记和源码控制有一个附加好处,你能基于这些标记自动生成变更日志。CSS Lint的构建系统能够在每次发布是自动生成一个包含提交信息及其贡献者的变更日志。这样变更日志不仅只是一个代码变更记录,也是社区贡献值的记录。
可用宣告
每当项目发布一个新版本时,都应该在某处发布宣告。不论是在你的博客或邮件列表或是在两者上都发布,正式宣告项目新版本已经可用是非常重要的。这份宣告应该包括项目代码的主要改动及其贡献者。对贡献者工作的认同是对他们的大鼓励,能从贡献代码中获得更多的认同感他们更有动力做更多的贡献。所以给予那些耗费无数精力在你的项目中的开发者以大的赞扬吧。
管理代码贡献
万事俱备,下一步是解决如何接受代码贡献。 你的贡献模型是非常规范还是很随意,取决于你的喜好和目标。对应个人项目,可能不需要什么规范的贡献流程。开发者指南应该说明合并代码到仓库的必要条件,一个提交先要满足这些条件才会被接受。对于更大的项目,应该要有更多规范的策略。
首先要考虑的是是否需要一个贡献者许可协议(CLA)。CLA在很多大型开源项目中使用以保护项目的合法权利。每位提交代码的开发者都需要同意CLA,以承诺任何贡献的代码都是原创的同时将代码的版权移交给项目所有。CLA也赋予项目所有者将贡献的代码作为项目一部分的授权,而且要求贡献者保证不会故意将他人具有版权、专利或其他权利的代码包含在自己的代码中进行提交。jQuery, YUI 和 Dojo 在代码提交时都要求贡献者同意CLA。如果你正在考虑使用CLA,那么寻求一些法律咨询是很值得的。
接下来,你可能想要为项目的工作人员建立一个权限层次。开源项目一般都会设置三个主要的角色:
贡献者
任何对项目做过代码贡献的人都可以算作贡献者。贡献者不能直接访问代码仓库,但是提交的补丁可以被接受。
提交者
提交者有权限直接访问代码仓库。他们经常对项目做特性添加和bug修正,也能够直接提交代码到代码仓库。
审查者
审查者是更高一级的贡献者,是能够对项目产生直接影响的指挥官。他们的职责是审查贡献者和提交者提交的代码,批准或者否决补丁,任命或者撤销提交者称号,总的来说是运作这个项目。
如果你打算采用刚才所说的权限层次,那么接下来需要起草一份文档来描述每种类型的贡献者的角色和贡献者角色如何通过排名来进行提升。YUI近创建了一个很正式的“贡献者模型”,有很的文档来描述角色和职责。
目前CSS Lint没有CLA,也没有正式的贡献者模型,但是每个人都应该在自己的开源项目成长过程中认真考虑这件事。
证明
从CSS Lint第一次发布到形成一个全功能的开源项目大概花了我们差不多6个月时间。从那时开始,超过一打的贡献者提交的代码被接受。尽管这个数字按照一个大型开源项目的标准来说有点少,但我们仍然对此感到骄傲。获得一次外部贡献很容易,在很长一段时间内都能持续获得帮助可不容易。
而且我们明白自己做的所有努力都是正确的,原因是收到的积极反馈。乔纳森·克莱因近到项目的邮件列表里问了几个问题,在后他也提交了一个pull request并被项目接受了。接着他给我发了一封反馈邮件:
我想说CSS Lint是开源项目的典范-文档,扩展方便,代码简洁,反馈及时,定制方便。基于CSS Lint做开发像阅读wiki一样容易,而且事实上你提出的特有更改工作流使得项目的进入门槛变得很低。我希望有更多的开源项目能照着做,让开发者为其做共享更容易。
对CSS Lint来说收到这样的邮件已经是司空见惯的事了。如果你愿意花点时间为自己的项目建立一个可持续发展的生态系统,这种事在你的项目里也一样会成为常态。每个人都希望自己的项目能成功,都希望有大量的开发者来做贡献。但是像乔纳森说的一样:尽量降低门槛,开发者们自然会找到方法来帮忙的。