做一個優秀的開源專案 需要注意哪些方面？

jobbole發表於2014-01-26

　　摘要

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

  • 清晰的依賴性和安裝說明
  • 至少有一個簡要的文件指南
  • 修改日誌和倉庫中的標籤
  • 關於支援的語言、執行時、工具版本的資訊和專案的成熟度
  • 一個可以讓使用者提問和交流的郵件列表

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

　　怎樣讓你的開源專案更棒

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

　　這有一個經驗法則：

　　不要讓你的使用者生氣！

　　也可以理解為：

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

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

　　建立一個實用的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上工作將近兩年後，我可以自信地說，我們的使用者最感謝我們的就是我們寫的專案文件：

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

　　我們為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

相關文章