我们在工作中很多时候都要做技术选型,去找寻既能满足自己需求又靠谱的第三方库;在前端开源生态季度繁盛的现状下,只要不是太小众的需求,我们很容易就能找到一堆相关的开源库,那我们具体要怎么做决策呢?我的做法是,先阅读开源库的说明文档让自己有一个感性的认识,然后挑选出其中的两三个库来进行更深入更全面的了解。如此说来,这说明文档是不是就很像我们求职时的简历呢?“简历”关都过不了,何谈“offer”啊!
本文将介绍一个库(即不局限于前端领域)所要具备的说明文档,主要包括 README.md、CHANGELOG.md、LICENSE,这些说明文档均需放置于项目的根目录。
当我们进入 GitHub 中的某一个开源代码仓库页面,除了项目信息、代码目录结构外,最先映入眼帘的就是 README.md 了,可见,其重要性不亚于 index.html 之于一个网站。
README.md 需要满足以下这些要求:
README.md
console.log('code in javascript');
一份优秀的 README.md 需要包含以下内容:
>
开头;尽量保持简洁且字数应少于120;与 GitHub 仓库(如果有的话)和 npm 包(同样是如果有的话)的描述保持一致。<script>
加载 CDN 资源。除了以上必须包含的内容外, README.md 中还有一些对用户友好的内容项,这些内容项往往会为你的库增色不少,所以如果可以的话,也请为你的库 README.md 加上:
CHANGELOG.md 记录了本库每个正式发布的版本,以及该版本所包含的内容。对于 GitHub 开源库来说, CHANGELOG.md 中的内容应该与 GitHub 中的 releases 保持一致。
CHANGELOG.md 具体包含以下内容:
如果你觉得维护 CHANGELOG.md 比较困难,那么其实也有工具可以从库每次的 commit message 中分析生成 CHANGELOG.md ,但这对 commit message 的规范性有一定要求,本系列后续的文章里会有详细的介绍。
LICENSE 是本库的版权声明,声明用户可以在什么范围内使用、二次开发、商用本库,具有法律效力,一般可以直接声明使用现成的协议,如 GPL / BSD / MIT/ Mozilla / Apache / LGPL 等,本文不打算介绍如何选择合适的协议,可参考《如何选择开源许可证?》。
LICENSE 对于商业项目的技术选型有这一票否定的地位,因为某些开源协议具有传染性,若你的项目使用了这样的开源库,则你的项目也必须开源,这对于商业项目来说几乎是不可接受的。
主流前端框架 React ,就曾因 LICENSE 问题,引发社区强烈不满,并遭到不少大型公司弃用,最终迫于压力下才改用最宽松的 MIT 协议,这才平息了风波。
请正确评估你所开发的库的用户群体,如果库的用户群体中包含他国人员,请为他们准备好合适语言的说明文档。而对于一个把源码托管在公共代码仓库的开源项目来说,我建议至少准备中英文两套说明文档,这将大大扩展开源库的用户群,毕竟既然辛辛苦苦做出来个开源库,总还是想多收获点 Star 和 Fork 的嘛嘿嘿~~
一般我们将默认一个说明文档是使用英语的,而把使用其它语言的说明文档的文件名上加上 IETF 语言代码,如简体中文的 IETF 语言代码是zh-CN
,因此 README.md 的中文文档命名是README.zh-CN.md
, CHANGELOG.md 的中文文档命名是CHANGELOG.zh-CN.md
,而 LICENSE 则只需要一份英文版的就足够了。
我会以我最近写的两个开源库:javascript-library-boilerplate 和 vue-directive-window 来作为实例项目代码来辅助介绍。
javascript-library-boilerplate 是一个现代前端生态下快速构建 javascript 库的脚手架(或称种子项目,或称示例代码,看你理解了),本库支持 GitHub 的 repository templates 功能,你可以直接在项目首页点击 Use this template 来直接套用本脚手架的代码来创建你自己的 javascript 库。
vue-directive-window 是一个可以快速让模态框(modal)支持类窗口操作的增强库;类窗口操作主要包括三大类:拖拽移动、拖拽调整窗口尺寸、窗口最大化; vue-directive-window 支持以 Vue 自定义指令或是一般 js 类的方式来调用。
vue-directive-window 相对于 javascript-library-boilerplate 来说,更贴近 Vue 生态圈,如果你最近想为 Vue 生态圈添砖加瓦,不妨参考一下本项目。
想要阅读更多我的技术文章?请到我的 GitHub 博客 Array-Huang/blog 来,如果对您有帮助的话请 Star&Watch 走一波哈(〃^ω^)
免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。