摘要

如果你想發布一個開源庫，請確保它有以下特點：

• 清晰的依賴性和安裝說明
• 至少有一個簡要的文檔指南
• 修改日志和倉庫中的標簽
• 關于支持的語言、運行時、工具版本的信息和項目的成熟度
• 一個可以讓用戶提問和交流的郵件列表

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

怎樣讓你的開源項目更棒

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

這里有一個經驗法則：

不要讓你的用戶生氣！

也可以理解為：

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

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

創建一個實用的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，為你的項目創建一個獨立的帳號，就像我們的@ClojureWerkz。

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

如果你需要一個例子，Welle README有一節關于社區和支持的。

怎么把它搞糟

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

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

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

傳給別人

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

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

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

怎么把它搞糟

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

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

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

最后的思考

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

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

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

原文鏈接： ClojureWerkz   翻譯： 伯樂在線 - archychu
譯文鏈接： http://blog.jobbole.com/57767/