做一個優秀的開源項目，需要注意哪些方面？

如果你想釋出一個開源庫，請確定它有以下特點：

• 清晰的依賴性和安裝說明
• 至少有一個簡要的文檔指南
• 修改日志和倉庫中的标簽
• 關于支援的語言、運作時、工具版本的資訊和項目的成熟度
• 一個可以讓使用者提問和交流的郵件清單

缺少任何一項都會造成一些使用者的憤怒和沮喪，當然同時也浪費了時間。

​

怎樣讓你的開源項目更棒

每年，越來越多的人釋出了自己開發的庫并且它們開源。這裡我們分享一些我們經驗，以便你的使用者對你的庫滿意。

這裡有一個經驗法則：

不要讓你的使用者生氣！

也可以了解為：

不要讓你的使用者有想要砸電腦的沖動

現在讓我們通過一些努力來實作這個目标。

建立一個實用的README

即使你的項目有一個很棒的網站，潛在的使用者第一次接觸這個項目很可能就是通過閱讀README檔案。我們需要確定它很棒并且包含了有用的資訊。

提供依賴資訊

那麼說你會釋出你的開源項目。這說明你很聰明，真有你的！不幸的是，不是所有人都像你那樣，而且有一些人對這門語言或者你在做的系統完全不了解。這意味着對你來說很顯然的事情對他們來說就一點也不顯然了。

其中一件就是缺少依賴說明或者安裝說明

我到底怎麼安裝這個東西，難道不能說得清楚一些嗎?

這很快就能讓使用者生氣。在源代碼裡找你的包或者構件的名字是很煩人的，有些項目對構件使用一些特别有才的名字，完全不符合倉庫的名字。

讓你的使用者從這些糟糕的事情中脫離出來吧。問題是怎樣添加依賴性，理想狀況下可以通過複制粘貼一小段代碼。

如果需要例子的話可以點選

Welle

。

清楚的說明項目的成熟度

你在生産中使用這個項目有幾個月了嗎？你是否覺得它還是不完整的？你是否希望API在下一個版本會徹底地修改？你的項目是否在要求最多并且很老的項目中也能穩定安全的使用？

要把這些說得清楚。下次你就不會因為做了一個錯誤的介紹，但是沒有的提供任何項目成熟度的資訊而項目浪費一周的時間了。你會意識到幾句短短的話就能産生很大的影響。

運作時、語言、工具版本的文檔支援

當考慮到向後相容時，Clojure有一個很好的跟蹤記錄。它好的幾乎讓人難以置信。包括1.2到1.3的更新，之後的更新對絕大多數的項目來說就是一個簡單替換。同樣地，那些高于1.2的項目大多使用了最新的穩定版本。

然而，不會一直都是這樣。在某些情況下，未來版本的Clojure會打破相容性。我們怎麼讓我們的使用者不憤怒？通過在README中清楚的說明哪些版本是支援的。

這隻需要寫一行文字。這樣，在你釋出的那一周就少了抱怨，同時也減少了初學者的很多麻煩。

如果你需要一個例子，有一個來自

Welle 的例子

說明你使用了什麼許可證

你可能并不太關心許可證，但是那些在大公司中想用你的庫的人很關心。他們必須知道！當他們想用Clojure/

Node.js

/Scala/Go等等的時候，可能不能使用。

是以清楚的說明你的許可證。也請你使用一些對商業友好的協定，除非你有自己的理由。（

Apache Public License 2.0

和

Eclipse Public License

）是不錯的選擇。注意到一些許可證(比如MIT)的确很友好、流行，但是不提供任何專利保護，在目前的法律環境下也不應該忽視。

最後，記得你可以使用雙許可證，如果你真的是許可證中立的話可以使用，比如APL2/GPLv2。那個你的使用者就可以選擇最适合他們的許可證了。

疑惑的時候，可以參考

摘要：合法、開源許可證用白話概括

（但是别把它當作合法的建議）

怎麼把它搞糟

如果你想坑你的使用者，可以試試：

• 在你項目的根目錄放一個空的README
• 在末尾寫上“歡迎加更新檔”
• 發明你自己的許可證或者使用一個完全不熟悉的，比如 WTFPL

那麼你的項目就永遠不會有使用者了。我保證。

為你的項目寫文檔

寫文檔不容易同時也是需要花費一些時間的。然而，文檔是你能為你的使用者做的最好的事了。不僅能夠節省他們大量的時間，也可以讓他們确信你的庫不是被遺棄的軟體。

文檔能夠讓你的使用者完成他們起初使用你的庫的任務。像Rob Pike說的，它“讓這些任務成為可能”。這讓你的使用者知道你重視這一點，讓他們知道你是個有血有肉的人，不是一個産生代碼的機器。

在

ClojureWerkz

上工作将近兩年後，我可以自信地說，我們的使用者最感謝我們的就是我們寫的項目文檔：

• [Elastisch documentation]
• [Welle documentation]
• [Neocons documentation]
• [Monger documentation]
• [Langohr documentation]

寫出優秀的文檔

需要花些時間。幸運的是，現代工具可以幫到你并且大大減少你必須解決的一些煩人的事。

我們為ClojureWerkz項目開源了我們的

基于Jekyll的文檔模闆

。我們在CSS和設計中視覺效果方面不是很擅長，是以我們使用了Twitter的

BootStrap

庫。我們的文檔站點可以更好看，但是相比大多數開源項目來說已經很不錯了。你可以使用我們的模闆或者為你的項目開發類似的工具。

更好的是，如果你開源了你的文檔站點(這似乎沒有理由不那麼做)，你會看到人們會比貢獻代碼的修改更早的貢獻出小的改進。

如果你仍然不确定是否值得為你的項目寫文檔，看一下 Jacob Kaplan-Moss的

這個報告

：

• 不要寫一個文檔說明，甚至連例子也不寫
• 確定你的API說明已經有三個月沒有更新了
• 聲明那些不願意讀代碼去了解即使是最基本的東西的使用者是愚蠢的，并且應該去賣漢堡！

更容易更新

某些時候，你想要發行項目的另一個版本。這可能是讓你的使用者很開心，因為他們已經使用了你的庫，或者很生氣，浪費了他們時間。

不關心向後相容

關于軟體開發的一件很令人生氣的事就是當你更新一個庫但是數百個測試失敗了。更讓我生氣的就是我還要重寫我一半的基礎代碼，因為有人在沒有任何警告的前提下決定打破公共的API。

是以，緻力于維護向後相容性。當然你沒有必要像OpenJDK那樣支援15年以前的項目。但是在移除之前建議不使用一些東西能夠更容易發現哪些地方改動了。

你怎麼做到這點呢？維護一個修改日志。

擁有一個修改日志

有時，你的使用者會更新（關于這一點在下文會更多的介紹）。他們會問自己一個問題：

這次釋出改動了什麼地方呢？

然後

我的代碼會不能用嗎？我是不是一定要重寫？

最後

Joe，那個運維的家夥會因為我更新讨厭我嗎？

所有這些問題都能通過一個修改日志得到解答。它像推特一樣隻不過它真的很實用，它是這樣用的：

• 每次你解決一個bug，在日志裡加一個簡單的記錄
• 每次你加入一個新特性，在日志裡簡單地提一下，并且用幾個代碼例子解釋它。
• 每次你做了重大的API改動，在日志中用粗體清楚的說明

就是這些了。沒有第三步！

修改日志一般把最新的記錄放在最前面。改動是按版本分類的。如果你有多個分支(比如master和1.0.x)，每一個都應該有一個獨立的修改日志。

就是這些了。可以看看，

Welle的修改日志

給版本加上标簽

又是那個時候了，你已經更新版本并且馬上就要釋出構件了。停一停，先做一件事：給這次送出加上标簽。沒有标簽的話，找兩個版本之間的不同會很痛苦的。

一些依賴性(比如Bundler, Rebar)和配置管理工具可以使用标簽，開發者系統這些标簽是可用的。

使用統一的版本資訊，比如v1.0.0-alpha1, v1.0.0, v1.1.2等。标簽不一緻絕對會導緻運維的人整天讨厭你的項目。

宣布版本發行

在你釋出一個版本字之後就是要寫一個部落格日志，或者在你們項目的郵件清單或更大的相關的郵件清單中發個更新(比如

Clojure郵件清單

或者

RabbitMQ

)

確定主題是以ANN或者[ANN]開頭的，這意味着這是一個通告。比如

ANN Welle 1.5.0 釋出了

在你的通告中，清楚的說明你的項目是做什麼的，它是否向後相容，并且有到修改日志的連結，可以讓使用者找到更多的細節。就是這樣了。

開發時使用預覽或者快照版本

你有沒有曾經看到一個項目用同一個版本，比如0.2.1将近半年？你怎麼知道哪一個版本才是0.2.1呢？這是一個還在開發中的版本嗎？是不是有人更新後忘了修改版本号？到底怎麼回事？

這會讓所有的開發者瘋掉的！千萬别做那樣的人！在項目中用預覽或者快照版本，當你快要釋出一個版本的時候才揭開那個版本。然後立即更新那個版本。

舉幾個開發版本的例子：

• 1.1.0.pre1
• 1.1.0-alpha1
• 1.1.0-SNAPSHOT

任何其他開發版本的命名格式是不清楚的，并且會你的使用者很不愉快。

如果你想完全坑你的使用者，試試下面：

• 随意打破公用的API，最好巧妙地，連你的測試也不會發現API的修改
• 忘了更新版本資訊
• 從不給版本加标簽
• 從不宣布版本發行

使用GitHub

我和 GitHub沒有友好關系，也不要假設Git是“最好”的版本控制系統。但是它真的不錯。最近幾乎所有人都在使用GitHub。

GitHub讓下面幾件事變得更簡單：

• 發現你的項目
• 浏覽和搜尋代碼
• 通過填問題或者@使你能夠關注問題
• 為小的改動做出貢獻

可能最重要的是，GitHub對不是技術大牛的很友好。是的，它的确是，同時他們正努力讓它變得更好。

使用GitHub意味着你能尤其簡單地使用CI的服務(

Travis CI

)。

如果你不讓你的使用者去處理更新檔、為了送出問題在網上到處找你的email、通過糟糕的3G網絡複制你300M的倉庫隻是為了編輯一個排版錯誤，你将得到更多的贊賞。

@old_sound @g3rtm bitbucket毫無疑問是很好的服務。但對于使用公開代碼的人開始顯得有點難了。– Michael Klishin (@michaelklishin) 21 de enero de 2013

不要把事情弄得困難。

提供一個讓使用者可以得到幫助的地方

如果你的項目達到了一定程度的流行度，你必須回答關于它的一些問題。為了這一點，設定一個郵件清單(一個Google群)或者如果你經常上IRC的話，開啟一個通道吧。

認為你沒有足夠的時間？使用郵件清單最好的部分就是如果你給了一個途徑，使用者會互相幫助。是以在你項目的README中清楚地說明可以獲得幫助的途徑。

在Twitter上經常搜你項目的名字，你就會發現各種各樣的問題，批評和表揚的。如果你頻繁地使用Twitter，為你的項目建立一個獨立的帳号，就像我們的@

這可以讓你建立一個社群，讓你知道人們是怎麼使用你的項目的、還有什麼地方可以提高。最後，它會幫助你找到可以幫助你維護你項目的人。這不僅能節省你的時間，也會鼓勵人們到處宣傳你的項目。

如果你需要一個例子，

Welle README

有一節關于社群和支援的。

• 關閉你Github上問題的功能
• 用開發協定，那麼使用者必須寫紙質信到坦尚尼亞
• 即使在README中修改了一行也要使用更新檔
• 把你的項目放到Darcs，即使它是Ruby、JavaScirpt或者Clojure的項目
• 讓人們很難找到項目在哪兒

這可以防止人們為你的項目做出貢獻或者從你地方偷一點想法。

傳給别人

到了一定時候，你可能對維護你的項目變得不感行卻了。可能你已經換了一個新工作，或者不再使用你自己的項目了。在郵件清單中宣布這件事，讓其他人來接管這個項目。不久以後，有人會來幫忙的。在Github上對這種事是有好處的，特别是他們已經公布了一個讓你轉你倉庫管理權的新特性。

不管你做什麼，不要讓你的項目變成沒人負責的項目。這是最确信的方式可以讓你現在或者未來的使用者可以繼續小貓大屠殺。

把項目移交給别人總是比之後找借口更好的。

• 沒有解釋地直接停止貢獻代碼，回答郵件清單的問題
• 忽略送出請求，說他們的送出沒有用，應該送出其它
• 說你是一個一旦問題解決就沒有任何興趣的人

這樣就可以確定你的項目最後會被複制至少300次，最後一個代替的項目會被建立，因為搞清楚那個複制項目解決了那個問題是很煩人的。

最後的思考

正如你看到的，讓你的項目可以被接受不是那麼難吧。除了文檔說明，讓你的使用者不生氣，讓運維的人不讨厭你也不需要花太多的時間。

維護一個開源項目是需要時間和精力的。但是它也是有回報的。我從GitHub還在測試的時候就已經在使用它了，而且幾乎可以說沒有其它什麼事情讓我有更多的專業機會。我很高興我能有今天而不是活躍在開源社群。

如果你不想做一些很酷的事情，可能不要在第一時間就釋出它。