把一個庫開源，你該做些什么
把一個庫[1]開源非常簡單，僅需幾秒鐘。你所需要做的僅僅是把公共倉庫(public repository) 托管 (hosted) 在網(wǎng)上(GitHub, Bitbucket,等等)嗎？不！事實上，如果你對非?？岬牟⑶铱梢怨_使用的庫悉心照料的話[2]，這樣做對每個人都是件更好的事情。來看下這些是怎么做到的。
README的編寫
README文件在你的項目中占據(jù)首要地位。你的項目必須包含它！這個文件必須包含庫的名字和一個關(guān)于它(簡短的)描述。把描述這一章節(jié)當(dāng)作是電梯游說 (elevator pitch，在乘電梯的30秒內(nèi)清晰準(zhǔn)確地向客戶解釋清楚解決方案)。
然后是編寫使用章節(jié)。盡可能詳細(xì)地用文字、代碼片段、截圖或者GIF格式的圖片，來描述如何使用你的庫。這個就是你項目的文檔, 你的庫很多時候也同樣如此, 這將會是你唯一提供的文檔。
先寫使用指南這部分并不是一個隨意的選擇。README文件應(yīng)該能吸引讀者(blow your reader's mind)，這樣他們就會使用你的庫并為它做出貢獻(xiàn)(或許不會)。
第三小節(jié)必須寫安裝方法。這個小節(jié)以*用戶*的角度說明怎樣快速安裝你的庫。如果有多種安裝方式，首先介紹你認(rèn)為最好的方式，然后才是(介紹)其他的。
你可以添加一個依賴章節(jié)，例如，依賴X的Y版本(Depends on X version Y) 。這個章節(jié)是可選的，可以不寫。
第四個必須編寫的小節(jié)是貢獻(xiàn)。盡管它可以使用一個CONTRIBUTING 文件代替。說明怎樣折騰你的庫(how to hack your library)，怎樣報告bugs，或者怎樣提交特性請求(submit feature requests)。這方面介紹一定要詳細(xì)。說明規(guī)則，讓收到的請求合并中避免評論每一行[3]，指引貢獻(xiàn)者使用恰當(dāng)?shù)墓ぞ?Point contributors to the right tools )，比如linters 或者 compilers。
你還必須添加一個測試章節(jié)。說明怎樣安裝測試套件，怎樣運行功能測試(functional tests)，以及需要安裝的工具。
如果你使用第三方的東西，或者打算列出貢獻(xiàn)者(當(dāng)然這個也可以寫在作者章節(jié))，那就添加一個信用(Credits)章節(jié)。這個章節(jié)是可選的，可以不寫。
最后還要記住，添加一個許可證章節(jié)!
模板如下(Markdown 語法)：
- project-x <-------- 一級標(biāo)題 (項目名字)
- =========
- project-x is a better way to achieve this and that, by leveraging the new API,
- blablabla.
- project-x用更好的方式實現(xiàn)某某功能，通過使用高效的新API，此處省略N個字。
- ## Usage(使用) <-------- 二級標(biāo)題
- ...
- ## Installation(安裝)
- ...
- ## Requirements(依賴)
- ...
- ## Contributing(貢獻(xiàn))
- See CONTRIBUTING file.
- 查看 CONTRIBUTING 文件。
- ## Running the Tests(執(zhí)行測試)
- ...
- ## Credits(信用)
- ...
- ## License(許可證)
- project-x is released under the MIT License. See the bundled LICENSE file for
- details.
- project-x 依據(jù) MIT許可證發(fā)布。詳細(xì)請看捆綁的 LICENSE 文件。
正如你所看到的, 我在模板里介紹了兩個文件: LICENSE(許可證)和CONTRIBUTING(貢獻(xiàn)指南)。貢獻(xiàn)這一小節(jié)的內(nèi)容用一個文件CONTRIBUTING代替了。LICENSE(許可證)這個文件里包含了你項目選擇的許可證，但你應(yīng)該選用哪個許可證呢？
許可證
我不想把所有的許可證都一一對比，你可以訪問tl;drLegal這個網(wǎng)站，它用易懂的話(simple words)向你介紹實用的(useful)開源許可證相關(guān)信息。
我傾向于使用 MIT許可證，因為它非常自由(liberal)。我這里的建議是參考下你的社區(qū)，選擇最恰當(dāng)?shù)囊粋€。比如說，在Symfony2 (一個PHP框架)社區(qū)，大多數(shù)相關(guān)的項目或者bundles 都是以MIT許可證發(fā)布的。而Java 的項目經(jīng)常以Apache許可證2.0(Apache License 2.0)發(fā)布的。
根據(jù)最近的報道(reports)，大多數(shù) GitHub上的項目沒有一個開源許可證。這是不好的(bad)！你必須得有許可證，即使是啤酒軟件許可證(Beerware license)。
正如Hacker News所提到的，精心(carefully)選擇你的許可證。并且，不要用你自己做的許可證或者僅僅聲明這個項目屬于公共領(lǐng)域 (Public domain，簡單來說作品已屬于全人類)。公共領(lǐng)域在國際上的確不是準(zhǔn)確定義的概念，意味著不同國家會有不同的理解。
即使你現(xiàn)在有一個文檔完善的庫和一個許可證，還是沒有“征服世界”(dominate the world)[4]。下面，我給出一個概覽，介紹在開源項目中我認(rèn)為重要的東西。
寫自動化測試(Write Tests & Automate)
我們可以通過開源項目寫優(yōu)美的代碼，因為這里沒有截止期限，也沒有“客戶”。記住，你項目展示了你能夠做什么。作為一個開發(fā)者，你的庫就是你的名片。
寫大量的測試！如果沒有提供一個測試套件，怎么去期望別人能為你的庫做出貢獻(xiàn)呢？因此, 寫測試, 和使用 Travis CI。 添加一個 .travis.yml 文件，描述怎么樣運行你的測試。這也是另一種方式寫如何運行測試的文檔。
在你的README文件里也添加一個狀態(tài)圖片(status image)。
留意一下(Take a look at)在線工具，例如PHP和JavaScript使用Scrutinizer , 或者 Puppet Linter。盡量使其自動化。
#p#
標(biāo)準(zhǔn)化(Be Standard)
在你的庫中使用恰當(dāng)?shù)墓ぞ?right tools)是非常重要的。再看一下你的社區(qū)，然后選擇大家常用(tend to use)的工具。在用PHP寫的程序里，大家都用 Composer 作為管理依賴關(guān)系的工具(dependency manager)。不要浪費時間去用PEAR或者其他工具，就用Composer。如果是一個Node.js庫，在npm上注冊它。Ruby 的開發(fā)者，請把你的庫作為gem發(fā)布(distribute your library as a gem)。C#的開發(fā)者，請使用NuGet。
另一個例子，在Symfony2里，在Resources/doc 里添加文檔是一個好的做法(good practice)。這是個慣例。不要重復(fù)出現(xiàn)你的文檔，而是在你的README文件里添加一個快速跳到文檔的鏈接。
管理問題(Issues)和版本發(fā)布(Releases)
GitHub，CodePlex，或者其他你喜歡的，他們都提供了追蹤問題(issue tracker)的工具，請使用它！
如果你使用GitHub，不要浪費時間在Wiki上。我從來沒有發(fā)現(xiàn)一個適當(dāng)?shù)墓ぷ髁鞒?decent workflow)。用README文件作為你的文檔，或者萬一(in case)文檔量很大(extensive documentation)的時候使用Read The Docs來做托管。使用 GitHub Issues 來管理里程碑，并用標(biāo)簽對問題進(jìn)行分類。
還有，嘗試盡快回復(fù)所有的問題…但be careful, and manage your time。對人友好，花時間幫助新來的人。非常值得去學(xué)習(xí)如何維護(hù)一個成功的開源項目。
另一個建議是，定期地打上版本標(biāo)簽來進(jìn)行發(fā)布(to release often by tagging versions periodically)。談起版本, 請關(guān)注(follow) Semantic Versioning Specification。
然后，用CHANGELOG(更改日志)這個文件來幫助用戶識別出你做出的更改。如果你不向后兼容，寫一個UPGRADE(升級)文件介紹說明如何升級。
你需要反饋！
我開源大量項目最主要的原因是，可以從用戶的反饋中學(xué)到很多東西。所以你需要反饋，我需要反饋，每個人都需要反饋！在Twitter，Hacker News等等上分享你的項目。讓全世界都知道！人們必須知道你的項目并不是因為它很出色，令人難忘，而是因為人們可以評論它。
使用 GitHub pages 為你的項目創(chuàng)建主頁，如果你愿意還可以買個域名，
還記得"征服世界"的計劃嗎？你要實現(xiàn)這個目標(biāo)幾乎需要到的，我們永遠(yuǎn)不知道。
雇人(Hire People)
一旦你"征服世界"，招收別人(enroll new people)[5]來幫助你非常重要這是非常棒的體驗。這樣會給你更多的時間來搞其他開源項目(也可以說是征服另一個世界的計劃) :-)
總而言之
讓一個庫開源不僅僅是發(fā)布源代碼。你還需要再做一些事情來讓別人更容易更愉快地使用它。為項目寫文檔展示了你的教學(xué)能力，這樣就可以找到恰當(dāng)?shù)脑~來表達(dá)你的想法。當(dāng)然，還說明了你在用心地做這件事。
不要忘記在你的庫里面添加測試，如果你在工作中不方便，回家再做。還有別忘了許可證，別找借口！
開源項目真的非?？?，但是要避免非我發(fā)明癥(Not Invented Here (NIH) Syndrome)。盡可能地做貢獻(xiàn)，而不是再開創(chuàng)一個已有的開源項目，重復(fù)造輪子。
你的庫或者項目：
- 必須有一個README文件，內(nèi)容包括名字，描述還有以下章節(jié)：使用方法，安裝指南，貢獻(xiàn)規(guī)范，如何測試和許可證；
- 必須有一個顯眼的許可證(MUST have a license that is visible)；
- 必須能測試(MUST be tested);
- 必須標(biāo)準(zhǔn)化或者符合你社區(qū)的慣例；
你：
- 需要反饋；
- 必須待人友善；
- 應(yīng)該招人(enroll people)。
順便說一下：如果你發(fā)現(xiàn)排版錯誤和錯別字。請派生(fork)和修改它。非常感謝！本文以Creative Commons Attribution-ShareAlike 3.0 Unported License許可證發(fā)表。
譯注：
-
I use “project” as a synonym of “library”,My blog post focuses on libraries as Open Source projects, rather than “projects” like products (applications). 原作者的開源項目主要是庫，所以這篇文章對其他類型的開源項目同樣適用。
-
原文：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
-
原文：Explain the rules to avoid commenting every single line in Pull Requests you receive.
-
it's a joke, 這是個玩笑。
-
作者原話：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 譯作 招收
原文地址: On Open Sourcing Libraries
譯文鏈接：http://funwo.tk/2013-08-06-on-open-sourcing-libraries-cn.html
