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

若是你想發佈一個開源庫，請確保它有如下特色：

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

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

怎樣讓你的開源項目更棒

每一年，愈來愈多的人發佈了本身開發的庫而且它們開源。這裏咱們分享一些咱們經驗，以便你的用戶對你的庫滿意。

這裏有一個經驗法則：

不要讓你的用戶生氣！

也能夠理解爲：

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

如今讓咱們經過一些努力來實現這個目標。

建立一個實用的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還在測試的時候就已經在使用它了，並且幾乎能夠說沒有其它什麼事情讓我有更多的專業機會。我很高興我能有今天而不是活躍在開源社區。

若是你不想作一些很酷的事情，可能不要在第一時間就發佈它。

---

原文：How to Make Your Open Source Project Really Awesome
轉載自：伯樂在線 - archychu