現代前端庫開發指南系列（三）：從說明文檔看庫的前世此生

前言

咱們在工做中不少時候都要作技術選型，去找尋既能知足本身需求又靠譜的第三方庫；在前端開源生態季度繁盛的現狀下，只要不是過小衆的需求，咱們很容易就能找到一堆相關的開源庫，那咱們具體要怎麼作決策呢？個人作法是，先閱讀開源庫的說明文檔讓本身有一個感性的認識，而後挑選出其中的兩三個庫來進行更深刻更全面的瞭解。如此說來，這說明文檔是否是就很像咱們求職時的簡歷呢？「簡歷」關都過不了，何談「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 走一波哈(〃^ω^)