现代前端库开发指南系列(三):从说明文档看库的前世今生

前言

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

本文将介绍一个库(即不局限于前端领域)所要具备的说明文档,主要包括 README.mdCHANGELOG.mdLICENSE,这些说明文档均需放置于项目的根目录。

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-boilerplatevue-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 生态圈添砖加瓦,不妨参考一下本项目。

系列文章目录(同步更新)

想要阅读更多我的技术文章?请到我的 GitHub 博客 Array-Huang/blog 来,如果对您有帮助的话请 Star&Watch 走一波哈(〃^ω^)

原文地址:https://blog.51cto.com/14632674/2458513

时间: 2024-10-27 07:10:33

现代前端库开发指南系列(三):从说明文档看库的前世今生的相关文章

现代前端库开发指南系列(一):融入现代前端生态

本系列文章讲什么内容? 本系列文章主要介绍如何在现代前端生态下,创建一个工业级别的库.近几年来,前端工程化.模块化.组件化的大潮铺天盖地而来,在解决以往的架构痛点之余,却又产生了信息过载的问题:我希望通过分享自己的经验,帮助大家少踩坑多出活. 为什么需要开发一个前端库呢? 在项目开发过程中,总有一些功能是相同或类似的,如果你只是单纯地复制粘贴这部分代码,那么恭喜你,假以时日,需求一改,你就只能自尝苦果了. 你说,这还不简单,抽成公共方法公用不就好了吗?对的没错,但请把视野再放广一点:在工作中,我

现代前端库开发指南系列(二):使用 webpack 构建一个库

前言 在前文中,我说过本系列文章的受众是在现代前端体系下能够熟练编写业务代码的同学,因此本文在介绍 webpack 配置时,仅提及构建一个库所特有的配置,其余配置请参考 webpack 官方文档. 输出产物 构建一个库与构建一个一般应用最大的不同点在于构建完成后输出的产物. 一般应用构建完成后会输出: 一个 html 文件 一个 js 入口 chunk .若干子 chunk 若干 css 文件 若干其它资源,如图片.字体文件等 虽然输出的资源非常多,但实际上所有的依赖.加载关系都已经从 html

phonegap 开发指南系列(3) ----在Eclipse中Android开发环境搭建

  前提条件:已在Eclipse中安装好Android SDK 和 ADT. 1.下载PhoneGap,解压. 2.用Eclipse新建一个安卓项目. 3.将phoneGap解压包里的Android文件夹下的phonegap-1.0.0.js 复制到安卓项目的 /assets/www/ 目录下. 4.将phoneGap解压包里的Android文件夹下的phonegap-1.0.0.jar 复制到安卓项目的 /libs 目录下. 5.在/assets/www/目录下新建一个index.html,内

iOS开发UINavigation系列三——工具栏UIToolBar

iOS开发UINavigation系列三--工具栏UIToolBar iOS中除了UINavinationBar之外,还有工具栏UIToolBar可以供我们使用,工具栏和导航栏十分类似,只是功能更加简单,工具栏中也有UIBarButtonItem按钮,在前两篇博客中,对导航栏和导航项都进行的讨论,地址如下: UINavigationBar:http://my.oschina.net/u/2340880/blog/527706 UINavigationItem:http://my.oschina.

web前端知识大纲:系列三 html篇

web前端庞大而复杂的知识体系的组成:html.css和 javascript 三.HTML 1.BOM BOM 是 Browser Object Model的缩写,即浏览器对象模型,当一个浏览器页面初始化时,会在内存创建一个全局的对象,用以描述当前窗口的属性和状态,这个全局对象被称为浏览器对象模型,即BOM.BOM的核心对象就是window,window对象也是BOM的顶级对象,其中包含了浏览器的 6个核心模块: document -即文档对象,渲染引擎在解析HTML代码时,会为每一个元素生成

蚂蚁区块链BaaS平台应用开发指南(三):从一个简单合约开始

Could IDE的入口 新版的Cloud IDE已经去除证书配置的要求,开发者开通区块链之后可直接开始智能合约的开发.在本节中,我们将会使用Could IDE来进行合约的编写.编译和调试的工作.如果是体验链,请在新手引导引导界面,找到合约体验链卡片,点击调试合约. 如果是正式的托管链或区块链创新大赛的链,通过合约管理>新建工程或编辑已有工程进入Cloud IDE. 从一个最简单的合约开始 选择目标链 编译部署合约前,要指定好所要部署的链以及部署用的账户:在右边栏中,点击环境配置: 在本例中,选

JNI/NDK开发指南(三)——JNI数据类型及与Java数据类型的映射关系

转载请注明出处:http://blog.csdn.net/xyang81/article/details/42047899 当我们在调用一个Java native方法的时候,方法中的参数是如何传递给C/C++本地函数中的呢?Java方法中的参数与C/C++函数中的参数,它们之间是怎么转换的呢?我猜你应该也有相关的疑虑吧,咱们先来看一个例子,还是以HelloWorld为例: HelloWorld.java: package com.study.jnilearn; class MyClass {}

【前端】开发指南

可用性 咋地了, DOCTYPE? 不定义DOCTYPE是一种可以被判死刑的罪行. 以前你可能用的是下面的DOCTYPE,不过你要知道现在已经有更简洁清晰的代码取而代之了. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 理想的状况是用HTML5 DOCTYPE,所有现

web多终端开发学习系列(三)--- 基于bootstrap的表格插件bootstrap-table

基于网页管理系统的开发大多数功能只是对数据的显示与操作,对于数据的显示一般都是通过table表格来显示,所以管理系统的开发很有必要引入表格插件,对于sencha touch等商业化框架,都有自己自带的表格控件,而对于bootstrap需要引入第三方的表格插件,这里我学习下bootstrap table. 介绍 bootstrap table是基于bootstrap框架的一个表格插件,官网地址是http://wenzhixin.net.cn/p/bootstrap-table/docs/index