首先, 我要感謝 Github 讓開源變得如此簡單, 簡單到隻需要有勇氣就行.
門檻雖然降低了, 隻可惜大多數程式猿并沒有足夠(Hua)嚴(Xin)肅(Si)對待, 使得開源的項目就好像隻是公開的學習筆記, 無人問津, 完全喪失應有的意義.
本文稍許入門的聊聊, 如何讓你的項目嚴(Bi)肅(Ge)起來, 搞不好有人會來 Star, Fork, 甚至 Pull Request 呢!
項目名字當然是第一重要的, 不過一個好名字着實不好想. 是以, 項目描述(Description)是不能輕視的, 簡單一句話介紹好你的項目是什麼, 往往決定别人是否會繼續看你的 README.
Description 最好用英文, Github 是一個全球性的碼農社交網站, 你的項目不要排斥歪果仁嘛! 當然, 這不是重點, 重點是 Description 和 Name 一樣是搜尋關鍵字的索引來源, 對搜尋引擎友好, 它就會讓你的項目排名靠前, 這個好處你肯定是懂的.
什麼, 英文不好? 四六級沒過, 翻譯軟體總會用吧?
Topic (上圖底部那一行) 相當于項目的關鍵字, 同樣地有益于搜尋引擎提升關聯權重.
項目可以沒有 Description 和 Topic, 但一定不能沒有 README. 既然都開源了, 若有人無論是以何種方式看到了你的項目, 然後他卻不知道如何開始, 一切前功盡棄.
README 正如其名, 是希望看到項目的人第一個了解的就是這個檔案裡的内容, 以此引導他快速且恰當地用起來, 進而了解這個項目對他的價值.
内容怎麼寫? 你可以參考對你價值最大的開源項目, 參考它們是如何寫, 一定錯不了.
嗯, 你可能心裡犯嘀咕, 那個太專業了, 内容太詳事, 寫不來(其實是懶).
這裡捎帶些私貨為例, 介紹常見的兩種項目類型的 README 至少要寫些什麼:
交代庫是用來解決什麼問題,
示範庫基本(常用)的用法,
介紹使用時依賴(或安裝)的方法.
參見私貨: https://github.com/zhongl/config-annotation
為了友善别人使用, 你的庫最好支援所屬程式設計語言主流的建構方式進行依賴, 以 Java 為例最好是 Maven 和 Gradle, Scala 則是 SBT.
這裡安利一下 jitpack, 使用它可以很容易将一個 Github 上 JVM 庫項目自動建構并釋出, 遠遠比往 Maven Central Repository 釋出簡單.
交代服務是用來解決什麼問題的,
羅列服務跑起來最簡單的操作步驟,
介紹服務的常用啟動參數與配置.
參見私貨: https://github.com/zhongl/passport
同樣, 為了友善别人快速體驗你的服務, 或許提供現成 Docker Image 是個睿智的選擇.
Github 生态裡有對開源項目免費的 CI/CD 服務, 如 travis-ci.org, circleci.com. 強烈推薦使用它們幫助實作Docker Image 的持續建構與釋出.
上圖中那些徽章你一定見過. 它們是錦上添花之用, 可以突顯項目目前的狀态, 增強項目使用者的信心.
如果你是個對代碼品質要求比較高的人, 我這裡推薦下面的代碼狀态服務:
travis-ci.org 或 circleci.com
coveralls.io
codacy.com
它們提供漂亮的Badges
Github 在開源社群的建設上, 提供了很多便利的支援, 這裡不詳細展開, 如果你希望不僅僅是開源一個項目, 而是去打造一個社群, 那麼不妨去深挖一下 Github 的官方部落格或文檔, 你一定會獲益良多的.