把一個庫開源，你該做些什麼

把一個庫[1]開源非常簡單，僅需幾秒鐘。你所需要做的就是把公共倉庫(public repository) 託管 (hosted) 在網上(GitHub、 Bitbucket 等)麼？不是的！事實上，如果你想把你的專案公開，並加以悉心維護的話[2]，那對每個人都是件好事情。來看看我們該怎麼做

 

README的編寫

README檔案在你的專案中佔據首要地位。你的專案必須包含它！這個檔案必須包含庫的名字和一個關於它(簡短的)描述。把描述這一章節當作是電梯遊說 (elevator pitch，在乘電梯的30秒內清晰準確地向客戶解釋清楚解決方案)。

然後是編寫使用章節。儘可能詳細地用文字、程式碼片段、截圖或者GIF格式的圖片，來描述如何使用你的庫。這個就是你專案的文件, 你的庫很多時候也同樣如此, 這將會是你唯一提供的文件。

先寫使用指南這部分並不是一個隨意的選擇。README檔案應該能吸引讀者(blow your reader’s mind)，這樣他們就會使用你的庫併為它做出貢獻(或許不會)。

第三小節必須寫安裝方法。這個小節以*使用者*的角度說明怎樣快速安裝你的庫。如果有多種安裝方式，首先介紹你認為最好的方式，然後才是(介紹)其他的。

你可以新增一個依賴章節，例如，依賴X的Y版本(Depends on X version Y) 。這個章節是可選的，可以不寫。

第四個必須編寫的小節是貢獻。儘管它可以使用一個CONTRIBUTING 檔案代替。說明怎樣折騰你的庫(how to hack your library)，怎樣報告bugs，或者怎樣提交特性請求(submit feature requests)。這方面介紹一定要詳細。說明規則，讓收到的請求合併中避免評論每一行^[3]，指引貢獻者使用恰當的工具(Point contributors to the right tools )，比如linters 或者 compilers。

你還必須新增一個測試章節。說明怎樣安裝測試套件，怎樣執行功能測試(functional tests)，以及需要安裝的工具。

如果你使用第三方的東西，或者打算列出貢獻者(當然這個也可以寫在作者章節)，那就新增一個信用(Credits)章節。這個章節是可選的，可以不寫。

最後還要記住，新增一個許可證章節!

模板如下(Markdown 語法)：

正如你所看到的, 我在模板裡介紹了兩個檔案: LICENSE(許可證)和CONTRIBUTING(貢獻指南)。貢獻這一小節的內容用一個檔案CONTRIBUTING代替了。LICENSE(許可證)這個檔案裡包含了你專案選擇的許可證，但你應該選用哪個許可證呢？

 

許可證

我不想把所有的許可證都一一對比，你可以訪問tl;drLegal這個網站，它用易懂的話(simple words)向你介紹實用的(useful)開源許可證相關資訊。

我傾向於使用 MIT許可證，因為它非常自由(liberal)。我這裡的建議是參考下你的社群，選擇最恰當的一個。比如說，在Symfony2 (一個PHP框架)社群，大多數相關的專案或者bundles 都是以MIT許可證釋出的。而Java 的專案經常以Apache許可證2.0(Apache License 2.0)釋出的。

根據最近的報導(reports)，大多數 GitHub上的專案沒有一個開源許可證。這是不好的(bad)！你必須得有許可證，即使是啤酒軟體許可證(Beerware license)。

正如Hacker News所提到的，精心(carefully)選擇你的許可證。並且，不要用你自己做的許可證或者僅僅宣告這個專案屬於公共領域 (Public domain，簡單來說作品已屬於全人類)。公共領域在國際上的確不是準確定義的概念，意味著不同國家會有不同的理解。

即使你現在有一個文件完善的庫和一個許可證，還是沒有“征服世界”(dominate the world)^[4]。下面，我給出一個概覽，介紹在開源專案中我認為重要的東西。

 

寫自動化測試(Write Tests & Automate)

我們可以通過開源專案寫優美的程式碼，因為這裡沒有截止期限，也沒有“客戶”。記住，你專案展示了你能夠做什麼。作為一個開發者，你的庫就是你的名片。

寫大量的測試！如果沒有提供一個測試套件，怎麼去期望別人能為你的庫做出貢獻呢？因此, 寫測試, 和使用 Travis CI。 新增一個 .travis.yml 檔案，描述怎麼樣執行你的測試。這也是另一種方式寫如何執行測試的文件。

在你的README檔案裡也新增一個狀態圖片(status image)。

留意一下(Take a look at)線上工具，例如PHP和JavaScript使用Scrutinizer , 或者 Puppet Linter。儘量使其自動化。

 

標準化(Be Standard)

在你的庫中使用恰當的工具(right tools)是非常重要的。再看一下你的社群，然後選擇大家常用(tend to use)的工具。在用PHP寫的程式裡，大家都用 Composer 作為管理依賴關係的工具(dependency manager)。不要浪費時間去用PEAR或者其他工具，就用Composer。如果是一個Node.js庫，在npm上註冊它。Ruby 的開發者，請把你的庫作為gem釋出(distribute your library as a gem)。C#的開發者，請使用NuGet。

另一個例子，在Symfony2裡，在Resources/doc 裡新增文件是一個好的做法(good practice)。這是個慣例。不要重複出現你的文件，而是在你的README檔案裡新增一個快速跳到文件的連結。

 

管理問題(Issues)和版本釋出(Releases)

GitHub，CodePlex，或者其他你喜歡的，他們都提供了追蹤問題(issue tracker)的工具，請使用它！

如果你使用GitHub，不要浪費時間在Wiki上。我從來沒有發現一個適當的工作流程(decent workflow)。用README檔案作為你的文件，或者萬一(in case)文件量很大(extensive documentation)的時候使用Read The Docs來做託管。使用 GitHub Issues 來管理里程碑，並用標籤對問題進行分類。

還有，嘗試儘快回覆所有的問題…但be careful, and manage your time。對人友好，花時間幫助新來的人。非常值得去學習如何維護一個成功的開源專案。

另一個建議是，定期地打上版本標籤來進行釋出(to release often by tagging versions periodically)。談起版本, 請關注(follow) Semantic Versioning Specification。

然後，用CHANGELOG(更改日誌)這個檔案來幫助使用者識別出你做出的更改。如果你不向後相容，寫一個UPGRADE(升級)檔案介紹說明如何升級。

 

你需要反饋！

我開源大量專案最主要的原因是，可以從使用者的反饋中學到很多東西。所以你需要反饋，我需要反饋，每個人都需要反饋！在Twitter，Hacker News等等上分享你的專案。讓全世界都知道！人們必須知道你的專案並不是因為它很出色，令人難忘，而是因為人們可以評論它。

使用 GitHub pages 為你的專案建立主頁，如果你願意還可以買個域名，還記得”征服世界”的計劃嗎？你要實現這個目標幾乎需要到的，我們永遠不知道。

僱人(Hire People)

一旦你”征服世界”，招收別人(enroll new people)^[5]來幫助你非常重要這是非常棒的體驗。這樣會給你更多的時間來搞其他開源專案(也可以說是征服另一個世界的計劃) :-)
總而言之

讓一個庫開源不僅僅是釋出原始碼。你還需要再做一些事情來讓別人更容易更愉快地使用它。為專案寫文件展示了你的教學能力，這樣就可以找到恰當的詞來表達你的想法。當然，還說明了你在用心地做這件事。

不要忘記在你的庫裡面新增測試，如果你在工作中不方便，回家再做。還有別忘了許可證，別找藉口！

開源專案真的非常酷，但是要避免非我發明症(Not Invented Here (NIH) Syndrome)。儘可能地做貢獻，而不是再開創一個已有的開源專案，重複造輪子。

TL;DR
你的庫或者專案：

• 必須有一個README檔案，內容包括名字，描述還有以下章節：使用方法，安裝指南，貢獻規範，如何測試和許可證；
• 必須有一個顯眼的許可證(MUST have a license that is visible)；
• 必須能測試(MUST be tested);
• 必須標準化或者符合你社群的慣例；

你：

• 需要反饋；
• 必須待人友善；
• 應該招人(enroll people)。

順便說一下：如果你發現排版錯誤和錯別字。請派生(fork)和修改它。非常感謝！本文以Creative Commons Attribution-ShareAlike 3.0 Unported License許可證發表。

譯註：
1. I use “project” as a synonym of “library”,My blog post focuses on libraries as Open Source projects, rather than “projects” like products (applications). 原作者的開源專案主要是庫，所以這篇文章對其他型別的開源專案同樣適用。

2. 原文：add some love to your new shiny library you just made publicly available.

• love = take care of
• shiny = well, shiny is… shiny, something which is cool, and beautiful

3. 原文：Explain the rules to avoid commenting every single line in Pull Requests you receive.

4. it’s a joke, 這是個玩笑。

5. 作者原話：enroll = hire (more or less), but it’s not because of the previous sentence. You don’t hire people “for real” (like a company would do I mean) 因此我把 enroll 譯作“招收”