把一个库开源,你该做些什么

把一个库[1]开源非常简单,仅需几秒钟。你所需要做的就是把公共仓库(public repository) 托管 (hosted) 在网上(GitHubBitbucket 等)么?不是的!事实上,如果你想把你的项目公开,并加以悉心维护的话[2],那对每个人都是件好事情。来看看我们该怎么做

 

README的编写

README文件在你的项目中占据首要地位。你的项目必须包含它!这个文件必须包含库的名字和一个关于它(简短的)描述。把描述这一章节当作是电梯游说 (elevator pitch,在乘电梯的30秒内清晰准确地向客户解释清楚解决方案)。

然后是编写使用章节。尽可能详细地用文字、代码片段、截图或者GIF格式的图片,来描述如何使用你的库。这个就是你项目的文档, 你的库很多时候也同样如此, 这将会是你唯一提供的文档。

先写使用指南这部分并不是一个随意的选择。README文件应该能吸引读者(blow your reader’s mind),这样他们就会使用你的库并为它做出贡献(或许不会)。

第三小节必须写安装方法。这个小节以*用户*的角度说明怎样快速安装你的库。如果有多种安装方式,首先介绍你认为最好的方式,然后才是(介绍)其他的。

你可以添加一个依赖章节,例如,依赖XY版本(Depends on X version Y) 。这个章节是可选的,可以不写。

第四个必须编写的小节是贡献。尽管它可以使用一个CONTRIBUTING 文件代替。说明怎样折腾你的库(how to hack your library),怎样报告bugs,或者怎样提交特性请求(submit feature requests)。这方面介绍一定要详细。说明规则,让收到的请求合并中避免评论每一行[3],指引贡献者使用恰当的工具(Point contributors to the right tools ),比如linters 或者 compilers。

你还必须添加一个测试章节。说明怎样安装测试套件,怎样运行功能测试(functional tests),以及需要安装的工具。

如果你使用第三方的东西,或者打算列出贡献者(当然这个也可以写在作者章节),那就添加一个信用(Credits)章节。这个章节是可选的,可以不写。

最后还要记住,添加一个许可证章节!

模板如下(Markdown 语法):

正如你所看到的, 我在模板里介绍了两个文件: LICENSE(许可证)和CONTRIBUTING(贡献指南)。贡献这一小节的内容用一个文件CONTRIBUTING代替了。LICENSE(许可证)这个文件里包含了你项目选择的许可证,但你应该选用哪个许可证呢?

 

许可证

我不想把所有的许可证都一一对比,你可以访问tl;drLegal这个网站,它用易懂的话(simple words)向你介绍实用的(useful)开源许可证相关信息。

我倾向于使用 MIT许可证,因为它非常自由(liberal)。我这里的建议是参考下你的社区,选择最恰当的一个。比如说,在Symfony2 (一个PHP框架)社区,大多数相关的项目或者bundles 都是以MIT许可证发布的。而Java 的项目经常以Apache许可证2.0(Apache License 2.0)发布的。

根据最近的报道(reports),大多数 GitHub上的项目没有一个开源许可证。这是不好的(bad)!你必须得有许可证,即使是啤酒软件许可证(Beerware license)。

正如Hacker News所提到的,精心(carefully)选择你的许可证。并且,不要用你自己做的许可证或者仅仅声明这个项目属于公共领域 (Public domain,简单来说作品已属于全人类)。公共领域在国际上的确不是准确定义的概念,意味着不同国家会有不同的理解

即使你现在有一个文档完善的库和一个许可证,还是没有“征服世界”(dominate the world)[4]。下面,我给出一个概览,介绍在开源项目中我认为重要的东西。

 

写自动化测试(Write Tests & Automate)

我们可以通过开源项目写优美的代码,因为这里没有截止期限,也没有“客户”。记住,你项目展示了你能够做什么。作为一个开发者,你的库就是你的名片

写大量的测试!如果没有提供一个测试套件,怎么去期望别人能为你的库做出贡献呢?因此, 写测试, 和使用 Travis CI。 添加一个 .travis.yml 文件,描述怎么样运行你的测试。这也是另一种方式写如何运行测试的文档。

在你的README文件里也添加一个状态图片(status image)。

留意一下(Take a look at)在线工具,例如PHP和JavaScript使用Scrutinizer , 或者 Puppet Linter。尽量使其自动化。

 

标准化(Be Standard)

在你的库中使用恰当的工具(right tools)是非常重要的。再看一下你的社区,然后选择大家常用(tend to use)的工具。在用PHP写的程序里,大家都用 Composer 作为管理依赖关系的工具(dependency manager)。不要浪费时间去用PEAR或者其他工具,就用Composer。如果是一个Node.js库,在npm上注册它。Ruby 的开发者,请把你的库作为gem发布(distribute your library as a gem)。C#的开发者,请使用NuGet

另一个例子,在Symfony2里,在Resources/doc 里添加文档是一个好的做法(good practice)。这是个惯例。不要重复出现你的文档,而是在你的README文件里添加一个快速跳到文档的链接。

 

管理问题(Issues)和版本发布(Releases)

GitHubCodePlex,或者其他你喜欢的,他们都提供了追踪问题(issue tracker)的工具,请使用它!

如果你使用GitHub,不要浪费时间在Wiki上。我从来没有发现一个适当的工作流程(decent workflow)。用README文件作为你的文档,或者万一(in case)文档量很大(extensive documentation)的时候使用Read The Docs来做托管。使用 GitHub Issues 来管理里程碑,并用标签对问题进行分类。

还有,尝试尽快回复所有的问题…但be careful, and manage your time。对人友好,花时间帮助新来的人。非常值得去学习如何维护一个成功的开源项目

另一个建议是,定期地打上版本标签来进行发布(to release often by tagging versions periodically)。谈起版本, 请关注(follow) Semantic Versioning Specification

然后,用CHANGELOG(更改日志)这个文件来帮助用户识别出你做出的更改。如果你不向后兼容,写一个UPGRADE(升级)文件介绍说明如何升级。

 

你需要反馈!

开源大量项目最主要的原因是,可以从用户的反馈中学到很多东西。所以你需要反馈,我需要反馈,每个人都需要反馈!在Twitter,Hacker News等等上分享你的项目。让全世界都知道!人们必须知道你的项目并不是因为它很出色,令人难忘,而是因为人们可以评论它。

使用 GitHub pages 为你的项目创建主页,如果你愿意还可以买个域名,还记得”征服世界”的计划吗?你要实现这个目标几乎需要到的,我们永远不知道。

雇人(Hire People)

一旦你”征服世界”,招收别人(enroll new people)[5]来帮助你非常重要这是非常棒的体验。这样会给你更多的时间来搞其他开源项目(也可以说是征服另一个世界的计划) :-)
总而言之

让一个库开源不仅仅是发布源代码。你还需要再做一些事情来让别人更容易更愉快地使用它。为项目写文档展示了你的教学能力,这样就可以找到恰当的词来表达你的想法。当然,还说明了你在用心地做这件事。

不要忘记在你的库里面添加测试,如果你在工作中不方便,回家再做。还有别忘了许可证,别找借口!

开源项目真的非常酷,但是要避免非我发明症(Not Invented Here (NIH) Syndrome)。尽可能地做贡献,而不是再开创一个已有的开源项目,重复造轮子。

TL;DR
你的库或者项目:

  • 必须有一个README文件,内容包括名字,描述还有以下章节:使用方法安装指南贡献规范如何测试许可证
  • 必须有一个显眼的许可证(MUST have a license that is visible);
  • 必须能测试(MUST be tested);
  • 必须标准化或者符合你社区的惯例;

你:

  • 需要反馈;
  • 必须待人友善;
  • 应该招人(enroll people)。

顺便说一下:如果你发现排版错误和错别字。请派生(fork)和修改它。非常感谢!本文以Creative Commons Attribution-ShareAlike 3.0 Unported License许可证发表。

译注:
1. I use “project” as a synonym of “library”,My blog post focuses on libraries as Open Source projects, rather than “projects” like products (applications). 原作者的开源项目主要是库,所以这篇文章对其他类型的开源项目同样适用。

2. 原文:add some love to your new shiny library you just made publicly available.

  • love = take care of
  • shiny = well, shiny is… shiny, something which is cool, and beautiful

3. 原文:Explain the rules to avoid commenting every single line in Pull Requests you receive.

4. it’s a joke, 这是个玩笑。

5. 作者原话:enroll = hire (more or less), but it’s not because of the previous sentence. You don’t hire people “for real” (like a company would do I mean) 因此我把 enroll 译作“招收”

收藏 评论

相关文章

可能感兴趣的话题



直接登录
跳到底部
返回顶部