一個完整的開源庫必須包含

• 文檔
• 好的編譯需求
• 規範
• 測試
• 持續集成

文檔

對一個開源庫來說，文檔就是他的身分證。

而一個開源代碼庫除了代碼效能好，開發者用的順手之外，最重要的就是要讓使用者簡單的看懂，因此文檔非常重要。

而一個項目最常見的文檔包含:

1. README.md

   • README.md 就是一個項目的門面，這個檔案就好比以前整包html裡面index.html的概念
   • 所有資訊的入口都在這個檔案。
   • 如果沒有一個入口，根本無法快速了解這個開源庫。所以一個好的 README.md 裡面要有:
     • 開源庫的目的 : 是為了解決什麼問題而做的
     • 使用的方式 和 使用的場景
     • 其他資訊的鏈接

2. TODO.md

   • TODO會記錄項目的未來計劃與方向，這對於開源貢獻者和使用者都有很重要的意義，下面是TODO的例子

   TODO
    - [X] 已完成
    - [ ] 未完成
   In Progress
    - [X] 已完成
    - [ ] 未完成
   Done
    - [X] 已完成
    - [ ] 未完成
   

3. CHANGELOG.md

   • CHANGELOG記錄項目的變更日誌，會記錄每個版本做了哪些修復; 以及顯現版本的特色
   • 而在撰寫這一塊時，主要有幾個注意事項
     1. 是否能夠讓人一目了然版號之間變更的主要目的(這個檔案要傳達的消息)
     2. 不是git log貼上去就好哦

   git log是更細部的說明每次的調整，但是這個檔案(CHANGELOG.md)則是從整體上來看變動了哪些部分

4. LICENSE

   • open source專案會用到的，明確告訴地使用者你的授權模式。
   • 一般來說，如果只是希望版權只屬於自己，但允許大家做任何修改並且沒有其他限制，那麼MIT最適合。

   而世界上的開源許可證，大概有上百種。很少有人能理解它們的區別。通常會在最流行的六種之間---- GPL、BSD、MIT、Mozilla、Apache和LGPL ----做選擇。

   

   小提醒:這一塊會涉及法律問題喔 !!

5. CONTRIBUTING.md

   • 這個檔案基本上是介紹如何一起優化這個開源庫。

   貢獻(CONTRIBUTING)有很多形式，例如：

   1. 翻譯
   2. 寫文件
   3. 介紹如何build和改寫code
   4. 這邊可以提供一些專案目標（roadmap）的資訊，讓其他人知道你的目地。
   5. 提到一些這個專案不接受什麼貢獻(CONTRIBUTING)，避免有人不清楚問

總結

對於我們這些懶懶的工程師，文檔是非常麻煩的，有時候沒有靈感也會不知道文檔要做什麼，
所以這裡我把它拆成一個章節詳細說明，有任何不好的地方都歡迎留言告訴我喔。

明天見。

參考資料:

• 8102年如何寫一個現代的JavaScript庫(https://juejin.im/post/6844903687819640845)
• JavaScript庫架構實戰(https://codertw.com/%E7%A8%8B%E5%BC%8F%E8%AA%9E%E8%A8%80/698450/)