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

前言

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