把一個(gè)庫(kù)[1]開(kāi)源非常簡(jiǎn)單，僅需幾秒鐘。你所需要做的僅僅是把公共倉(cāng)庫(kù)(public repository) 托管 (hosted) 在網(wǎng)上(GitHub, Bitbucket,等等)嗎？不！事實(shí)上，如果你對(duì)非?？岬牟⑶铱梢怨_(kāi)使用的庫(kù)悉心照料的話[2]，這樣做對(duì)每個(gè)人都是件更好的事情。來(lái)看下這些是怎么做到的。

README的編寫(xiě)

README文件在你的項(xiàng)目中占據(jù)首要地位。你的項(xiàng)目必須包含它！這個(gè)文件必須包含庫(kù)的名字和一個(gè)關(guān)于它(簡(jiǎn)短的)描述。把描述這一章節(jié)當(dāng)作是電梯游說(shuō) (elevator pitch，在乘電梯的30秒內(nèi)清晰準(zhǔn)確地向客戶(hù)解釋清楚解決方案)。

然后是編寫(xiě)使用章節(jié)。盡可能詳細(xì)地用文字、代碼片段、截圖或者GIF格式的圖片，來(lái)描述如何使用你的庫(kù)。這個(gè)就是你項(xiàng)目的文檔, 你的庫(kù)很多時(shí)候也同樣如此, 這將會(huì)是你唯一提供的文檔。

先寫(xiě)使用指南這部分并不是一個(gè)隨意的選擇。README文件應(yīng)該能吸引讀者(blow your reader's mind)，這樣他們就會(huì)使用你的庫(kù)并為它做出貢獻(xiàn)(或許不會(huì))。

第三小節(jié)必須寫(xiě)安裝方法。這個(gè)小節(jié)以*用戶(hù)*的角度說(shuō)明怎樣快速安裝你的庫(kù)。如果有多種安裝方式，首先介紹你認(rèn)為最好的方式，然后才是(介紹)其他的。

你可以添加一個(gè)依賴(lài)章節(jié)，例如，依賴(lài)X的Y版本(Depends on X version Y) 。這個(gè)章節(jié)是可選的，可以不寫(xiě)。

第四個(gè)必須編寫(xiě)的小節(jié)是貢獻(xiàn)。盡管它可以使用一個(gè)CONTRIBUTING 文件代替。說(shuō)明怎樣折騰你的庫(kù)(how to hack your library)，怎樣報(bào)告bugs，或者怎樣提交特性請(qǐng)求(submit feature requests)。這方面介紹一定要詳細(xì)。說(shuō)明規(guī)則，讓收到的請(qǐng)求合并中避免評(píng)論每一行[3]，指引貢獻(xiàn)者使用恰當(dāng)?shù)墓ぞ?Point contributors to the right tools )，比如linters 或者 compilers。

你還必須添加一個(gè)測(cè)試章節(jié)。說(shuō)明怎樣安裝測(cè)試套件，怎樣運(yùn)行功能測(cè)試(functional tests)，以及需要安裝的工具。

如果你使用第三方的東西，或者打算列出貢獻(xiàn)者(當(dāng)然這個(gè)也可以寫(xiě)在作者章節(jié))，那就添加一個(gè)信用(Credits)章節(jié)。這個(gè)章節(jié)是可選的，可以不寫(xiě)。

最后還要記住，添加一個(gè)許可證章節(jié)!

模板如下(Markdown 語(yǔ)法)：

project-x     <-------- 一級(jí)標(biāo)題 (項(xiàng)目名字)  
=========  
 
project-x is a better way to achieve this and that, by leveraging the new API,  
blablabla.  
project-x用更好的方式實(shí)現(xiàn)某某功能，通過(guò)使用高效的新API，此處省略N個(gè)字。  
 
## Usage(使用)     <-------- 二級(jí)標(biāo)題  
...  
 
## Installation(安裝)  
...  
 
## Requirements(依賴(lài))  
...  
 
## Contributing(貢獻(xiàn))  
 
See CONTRIBUTING file.  
查看 CONTRIBUTING 文件。  
 
## Running the Tests(執(zhí)行測(cè)試)  
...  
 
## Credits(信用)  
...  
 
## License(許可證)  
 
project-x is released under the MIT License. See the bundled LICENSE file for   
details.  
project-x 依據(jù) MIT許可證發(fā)布。詳細(xì)請(qǐng)看捆綁的 LICENSE 文件。 

正如你所看到的, 我在模板里介紹了兩個(gè)文件: LICENSE(許可證)和CONTRIBUTING(貢獻(xiàn)指南)。貢獻(xiàn)這一小節(jié)的內(nèi)容用一個(gè)文件CONTRIBUTING代替了。LICENSE(許可證)這個(gè)文件里包含了你項(xiàng)目選擇的許可證，但你應(yīng)該選用哪個(gè)許可證呢？

許可證

我不想把所有的許可證都一一對(duì)比，你可以訪問(wèn)tl;drLegal這個(gè)網(wǎng)站，它用易懂的話(simple words)向你介紹實(shí)用的(useful)開(kāi)源許可證相關(guān)信息。

我傾向于使用 MIT許可證，因?yàn)樗浅Ｗ杂?liberal)。我這里的建議是參考下你的社區(qū)，選擇最恰當(dāng)?shù)囊粋€(gè)。比如說(shuō)，在Symfony2 (一個(gè)PHP框架)社區(qū)，大多數(shù)相關(guān)的項(xiàng)目或者bundles 都是以MIT許可證發(fā)布的。而Java 的項(xiàng)目經(jīng)常以Apache許可證2.0(Apache License 2.0)發(fā)布的。

根據(jù)最近的報(bào)道(reports)，大多數(shù) GitHub上的項(xiàng)目沒(méi)有一個(gè)開(kāi)源許可證。這是不好的(bad)！你必須得有許可證，即使是啤酒軟件許可證(Beerware license)。

正如Hacker News所提到的，精心(carefully)選擇你的許可證。并且，不要用你自己做的許可證或者僅僅聲明這個(gè)項(xiàng)目屬于公共領(lǐng)域 (Public domain，簡(jiǎn)單來(lái)說(shuō)作品已屬于全人類(lèi))。公共領(lǐng)域在國(guó)際上的確不是準(zhǔn)確定義的概念，意味著不同國(guó)家會(huì)有不同的理解。

即使你現(xiàn)在有一個(gè)文檔完善的庫(kù)和一個(gè)許可證，還是沒(méi)有“征服世界”(dominate the world)[4]。下面，我給出一個(gè)概覽，介紹在開(kāi)源項(xiàng)目中我認(rèn)為重要的東西。

寫(xiě)自動(dòng)化測(cè)試(Write Tests & Automate)

我們可以通過(guò)開(kāi)源項(xiàng)目寫(xiě)優(yōu)美的代碼，因?yàn)檫@里沒(méi)有截止期限，也沒(méi)有“客戶(hù)”。記住，你項(xiàng)目展示了你能夠做什么。作為一個(gè)開(kāi)發(fā)者，你的庫(kù)就是你的名片。

寫(xiě)大量的測(cè)試！如果沒(méi)有提供一個(gè)測(cè)試套件，怎么去期望別人能為你的庫(kù)做出貢獻(xiàn)呢？因此, 寫(xiě)測(cè)試, 和使用 Travis CI。 添加一個(gè) .travis.yml 文件，描述怎么樣運(yùn)行你的測(cè)試。這也是另一種方式寫(xiě)如何運(yùn)行測(cè)試的文檔。

在你的README文件里也添加一個(gè)狀態(tài)圖片(status image)。

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

#p#

標(biāo)準(zhǔn)化(Be Standard)

在你的庫(kù)中使用恰當(dāng)?shù)墓ぞ?right tools)是非常重要的。再看一下你的社區(qū)，然后選擇大家常用(tend to use)的工具。在用PHP寫(xiě)的程序里，大家都用 Composer 作為管理依賴(lài)關(guān)系的工具(dependency manager)。不要浪費(fèi)時(shí)間去用PEAR或者其他工具，就用Composer。如果是一個(gè)Node.js庫(kù)，在npm上注冊(cè)它。Ruby 的開(kāi)發(fā)者，請(qǐng)把你的庫(kù)作為gem發(fā)布(distribute your library as a gem)。C#的開(kāi)發(fā)者，請(qǐng)使用NuGet。

另一個(gè)例子，在Symfony2里，在Resources/doc 里添加文檔是一個(gè)好的做法(good practice)。這是個(gè)慣例。不要重復(fù)出現(xiàn)你的文檔，而是在你的README文件里添加一個(gè)快速跳到文檔的鏈接。

管理問(wèn)題(Issues)和版本發(fā)布(Releases)

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

如果你使用GitHub，不要浪費(fèi)時(shí)間在Wiki上。我從來(lái)沒(méi)有發(fā)現(xiàn)一個(gè)適當(dāng)?shù)墓ぷ髁鞒?decent workflow)。用README文件作為你的文檔，或者萬(wàn)一(in case)文檔量很大(extensive documentation)的時(shí)候使用Read The Docs來(lái)做托管。使用 GitHub Issues 來(lái)管理里程碑，并用標(biāo)簽對(duì)問(wèn)題進(jìn)行分類(lèi)。

還有，嘗試盡快回復(fù)所有的問(wèn)題…但be careful, and manage your time。對(duì)人友好，花時(shí)間幫助新來(lái)的人。非常值得去學(xué)習(xí)如何維護(hù)一個(gè)成功的開(kāi)源項(xiàng)目。

另一個(gè)建議是，定期地打上版本標(biāo)簽來(lái)進(jìn)行發(fā)布(to release often by tagging versions periodically)。談起版本, 請(qǐng)關(guān)注(follow) Semantic Versioning Specification。

然后，用CHANGELOG(更改日志)這個(gè)文件來(lái)幫助用戶(hù)識(shí)別出你做出的更改。如果你不向后兼容，寫(xiě)一個(gè)UPGRADE(升級(jí))文件介紹說(shuō)明如何升級(jí)。

你需要反饋！

我開(kāi)源大量項(xiàng)目最主要的原因是，可以從用戶(hù)的反饋中學(xué)到很多東西。所以你需要反饋，我需要反饋，每個(gè)人都需要反饋！在Twitter，Hacker News等等上分享你的項(xiàng)目。讓全世界都知道！人們必須知道你的項(xiàng)目并不是因?yàn)樗艹錾?，令人難忘，而是因?yàn)槿藗兛梢栽u(píng)論它。

使用 GitHub pages 為你的項(xiàng)目創(chuàng)建主頁(yè)，如果你愿意還可以買(mǎi)個(gè)域名，

還記得"征服世界"的計(jì)劃嗎？你要實(shí)現(xiàn)這個(gè)目標(biāo)幾乎需要到的，我們永遠(yuǎn)不知道。

雇人(Hire People)

一旦你"征服世界"，招收別人(enroll new people)[5]來(lái)幫助你非常重要這是非常棒的體驗(yàn)。這樣會(huì)給你更多的時(shí)間來(lái)搞其他開(kāi)源項(xiàng)目(也可以說(shuō)是征服另一個(gè)世界的計(jì)劃) :-)

總而言之

讓一個(gè)庫(kù)開(kāi)源不僅僅是發(fā)布源代碼。你還需要再做一些事情來(lái)讓別人更容易更愉快地使用它。為項(xiàng)目寫(xiě)文檔展示了你的教學(xué)能力，這樣就可以找到恰當(dāng)?shù)脑~來(lái)表達(dá)你的想法。當(dāng)然，還說(shuō)明了你在用心地做這件事。

不要忘記在你的庫(kù)里面添加測(cè)試，如果你在工作中不方便，回家再做。還有別忘了許可證，別找借口！

開(kāi)源項(xiàng)目真的非?？?，但是要避免非我發(fā)明癥(Not Invented Here (NIH) Syndrome)。盡可能地做貢獻(xiàn)，而不是再開(kāi)創(chuàng)一個(gè)已有的開(kāi)源項(xiàng)目，重復(fù)造輪子。

TL;DR

你的庫(kù)或者項(xiàng)目：

• 必須有一個(gè)README文件，內(nèi)容包括名字，描述還有以下章節(jié)：使用方法，安裝指南，貢獻(xiàn)規(guī)范，如何測(cè)試和許可證；
• 必須有一個(gè)顯眼的許可證(MUST have a license that is visible)；
• 必須能測(cè)試(MUST be tested);
• 必須標(biāo)準(zhǔn)化或者符合你社區(qū)的慣例；

你：

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

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

譯注：

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). 原作者的開(kāi)源項(xiàng)目主要是庫(kù)，所以這篇文章對(duì)其他類(lèi)型的開(kāi)源項(xiàng)目同樣適用。

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, 這是個(gè)玩笑。

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 譯作 招收

原文地址: On Open Sourcing Libraries

譯文鏈接：http://funwo.tk/2013-08-06-on-open-sourcing-libraries-cn.html