现代前端库开发指南系列（三）：从说明文档看库的前世此生

前言

咱们在工做中不少时候都要作技术选型，去找寻既能知足本身需求又靠谱的第三方库；在前端开源生态季度繁盛的现状下，只要不是过小众的需求，咱们很容易就能找到一堆相关的开源库，那咱们具体要怎么作决策呢？个人作法是，先阅读开源库的说明文档让本身有一个感性的认识，而后挑选出其中的两三个库来进行更深刻更全面的了解。如此说来，这说明文档是否是就很像咱们求职时的简历呢？“简历”关都过不了，何谈“offer”啊！

本文将介绍一个库（即不局限于前端领域）所要具有的说明文档，主要包括 README.md、CHANGELOG.md、LICENSE，这些说明文档均需放置于项目的根目录。

README.md

当咱们进入 GitHub 中的某一个开源代码仓库页面，除了项目信息、代码目录结构外，最早映入眼帘的就是 README.md 了，可见，其重要性不亚于 index.html 之于一个网站。

README.md 须要知足如下这些要求：

• 准确（包括字母大小写）命名为README.md
• 符合 markdown 语法
• 每一个章节都应有标题
• 中、英文链接处应有空格分隔
• 使用 markdown 语法包裹代码片断，并注意标注代码段的语言种类，如：

console.log('code in javascript');
复制代码

必须包含的内容

一份优秀的 README.md 须要包含如下内容：

• 名称：必须与库的名称保持一致。
• 简介：以 markdown 语法>开头；尽可能保持简洁且字数应少于120；与 GitHub 仓库（若是有的话）和 npm 包（一样是若是有的话）的描述保持一致。
• 库的安装方法：如何安装本库，在前端领域下一般指如何安装 npm 包或用<script>加载 CDN 资源。
• 库的使用方法：如何使用本库，可列出最简单的用法，让用户可以以最快的速度把库跑起来，这可以高效地创建起用户的信任。
• 开源许可协议：本库的版权声明，下文将详细介绍。
• API：包括库提供的方法、参数、事件等信息。

可选内容

除了以上必须包含的内容外， README.md 中还有一些对用户友好的内容项，这些内容项每每会为你的库增色很多，因此若是能够的话，也请为你的库 README.md 加上：

• 目录：带锚点跳转的连接，可以使用工具自动根据 README.md 的各级标题来生成，详情请参考 github-markdown-toc 。
• LOGO：一个好的 LOGO 会成为你的库的视觉识别标识，使你的库更容易被用户接受和记住。
• 徽章：徽章是由 shileds.io 提供的图片，图片上还能够按需附上超连接；徽章一般用于突出描述本项目在外部第三方平台的状态和数据，如项目的持续集成状态（若是本库配置有单元测试的话那通常还会包括代码测试覆盖率）、项目在某平台（前端领域一般指的是 npm）的下载量、项目最新发布的版本号、开源协议等。
• 浏览器兼容性：若是本库是在浏览器环境下运行的，那么声明本库的浏览器兼容性能够帮助用户快速完成技术选型。
• 安全风险：用于罗列本库当前已被发现且未解决的安全漏洞及其风险级别，若有绕过的方法也请附上，这一样能够帮助用户快速作技术选型。

CHANGELOG.md

CHANGELOG.md 记录了本库每一个正式发布的版本，以及该版本所包含的内容。对于 GitHub 开源库来讲， CHANGELOG.md 中的内容应该与 GitHub 中的 releases 保持一致。

CHANGELOG.md 具体包含如下内容：

• 版本号
  • 新特性(new features)
  • 优化(optimization)
  • Bug 修复(bug fixes)
  • breaking changes
  • 文档(docs)

若是你以为维护 CHANGELOG.md 比较困难，那么其实也有工具能够从库每次的 commit message 中分析生成 CHANGELOG.md ，但这对 commit message 的规范性有必定要求，本系列后续的文章里会有详细的介绍。

LICENSE

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-library-boilerplate 是一个现代前端生态下快速构建 javascript 库的脚手架（或称种子项目，或称示例代码，看你理解了），本库支持 GitHub 的 repository templates 功能，你能够直接在项目首页点击 Use this template 来直接套用本脚手架的代码来建立你本身的 javascript 库。

vue-directive-window

vue-directive-window 是一个能够快速让模态框(modal)支持类窗口操做的加强库；类窗口操做主要包括三大类：拖拽移动、拖拽调整窗口尺寸、窗口最大化； vue-directive-window 支持以 Vue 自定义指令或是通常 js 类的方式来调用。

vue-directive-window 相对于 javascript-library-boilerplate 来讲，更贴近 Vue 生态圈，若是你最近想为 Vue 生态圈添砖加瓦，不妨参考一下本项目。

系列文章目录（同步更新）

• 《现代前端库开发指南系列（一）：融入现代前端生态》
• • 《现代前端库开发指南系列（二）：使用 webpack 构建一个库》

想要阅读更多个人技术文章？请到个人 GitHub 博客 Array-Huang/blog 来，若是对您有帮助的话请 Star&Watch 走一波哈(〃^ω^)