手把手教你如何構建一個優秀的開源專案

overtrue發表於2017-07-13

file
這其實是之前在北京 Laravel Meetup 的一次分享內容,不過考慮到有很多人在公眾號想聽聽關於我是如何做開源這個話題,所以就再次拿它講一個文字版。

file

關於我,這個就沒啥可講的了,EasyWeChat 作者、Laravel China 創始人之一。

file

要想做好開源,這 8 個步驟缺一不可,當然這個過程週期是持續的,你會在不斷開源過程中提升自己,學到新的東西。

file

第一件頭疼的事情當然是 “做什麼?”,不過根據我的個人經驗來看,找一個開源專案 idea 並沒有想象的那麼難,一般有以下三個渠道:

第一個渠道是專案,因為大部分都是來自工作生活中,所以上圖我把“專案”排到第一位。很多時候在我們的開發工作中,會經常遇到重複性的工作,比如你每啟動一個專案都要搞一遍簡訊的傳送,又得去找一遍用哪家的服務,還得折騰一遍許可權系統,其實這些都是激發你創意的好時機。你會發現不是你一個人在重複,而是大家都在這樣不停的重複做很多原本不需要重複做的事情。所以這時候就是你造輪子的好時機。

第二個創意來源就是交流群,我相信大部分同學的 QQ 都有不少技術交流群吧,你會發現很多人在群裡會提重複的問題,或者一些伸手黨會經常來問一些“有沒有基於xxx的專案啊”、“有沒有人會xxx” 諸如此類的問題。如果你發現這個需求確實挺多的,並且也沒有一個好用的輪子,你就動手吧!

第三就是社群,一些論壇或者部落格,也是發現需求的地方,基本都是從別人的討論中發現創意,這些使用者就是你的專案最直接使用者。

file

做開源專案其實是一件比較費時費心的工作,它的最大難點並不在於程式碼,而是後期的維護持續的跟進。但是要想製作出一個受歡迎的開源專案,寫好程式碼永遠是關鍵的點,試想一下,一個人從你各種吹 B 的連結點到 GitHub,看到原始碼亂七八糟,格式不統一,駝峰+下劃線各種混寫,對齊也是 tab + space,註釋基本為 0 的時候那個場景,是很嚇人的,所以不管你的抽象能力怎麼樣,也不管你這個模組寫得是否是那麼的科學,請做好第一步:寫好程式碼。

上圖我列舉了一些名詞,難免有同學不認識,我這裡大概介紹一下:

PSR 是國際框架組織 PHP-FIG(PHP Framework Interop Group) 制定的一系列規範,包括不限於自動載入,編碼規範、快取以及其它一系列介面規範。它雖然不是 PHP 官方標準,但是目前大多數開源專案都是按這個標準來的,所以,有必要認真瞭解一下。

  • PHPCS 是 PHP Code Sniffer,一款程式碼規範檢查工具,可以根據你的設定來檢查程式碼規範性問題。
  • PHPCBF 是 PHPCS 內建的程式碼規範修復工具,大部分的程式碼規範問題它都可以自動修掉。
  • PHPMD 是程式碼複雜度檢測工具,能夠很方便的檢查你的程式碼是不是寫得複雜度過高。
  • StyleCI 是一款線上的程式碼規範檢查服務,最初的版本是開源的,後來閉源了,核心是基於 PHPCS 來完成。我的所有 PHP 開源專案基本都開通了這個服務來自動檢查。
  • Scrutinizer 同樣是一款線上服務,不過它的功能比較強大,主要用於檢查程式碼質量問題,比如潛在的 bug,未使用的變數,錯誤的型別約束,或者重複的程式碼等,總之是一款很棒的工具。
  • Travis-CI 是一款線上持續整合服務,自動化執行單元測試,或者部署任務等。

GitHub 上有很多類似的服務,你可以檢視上面的連結來了解它們,它們都是對開源專案免費使用的。

file

程式碼寫好了彆著急直接放到網上,做好了上面第二步我們提到的各種規範檢查外,充分的測試也是一個必要的工作。

一般的做法是寫單元測試,如果你還對單元測試這個東西不夠熟悉的話,是時候發起一波學習了。

在保證足夠覆蓋度的前提下,結合第二步提到的持續整合服務,這個專案差不多就是可以打 80 分了。

單元測試不僅能保證程式碼的可靠程度,同時在寫測試過程中你會發現你程式碼設計得不好的地方,我一直使用的一個評判標準就是:編寫單元測試的難度與程式碼質量成反比。

寫完測試可以把程式碼先提交了,但是不要忘記還有一個非常重要的事情沒做:寫文件。

file

友好的文件是你專案能否吸引別人目光的首要的判斷標準。文件都看不明白是個啥根本不可能有人敢用嘛。所以,在推廣前,我們第一件事情就是完善文件。如果你的專案不限於國內使用,那最好提供兩個版本,或者起碼提供英文版本的文件。有一些專案國外是沒法用的,比如我最近的輪子 overtrue/easy-sms,它是基於國內的簡訊運營商的,就算國外能用估計也沒有人用,所以這種場景下就寫中文說明就夠。

一說到寫英文,好多朋友第一句就會說:我英文很差啊。其實不要怕出錯,大膽去做就好,錯了再改。我一個四級都沒過的人不也一樣寫嗎,用好各種工具就可以。

如果專案比較小,一般 README.md 就夠,如果專案比較複雜,寫在 README 感覺太長,可以考慮以下三種方案:

第一種,最便捷的方案就是直接在專案裡放一個 docs 資料夾,使用 Markdown 分檔案寫文件。

第二種,使用 GitHub 官方提供的 Pages 服務建立一個站點,這個具體使用可以去了解一下官方指南。

第三種,就是最複雜的方案,自建網站,這種適用於中大型專案。

那麼,文件應該怎麼寫呢?請你一定要關注以下這些必要的點。

file
file

文件寫好了,我們應該釋出我們的版本,具體關於如何把 GitHub 專案提交到 packagist 我就不細講了,這個網上實在是太多講它的,如果你還是沒找到,就去 Laravel China 找到作者 Ryan 的文章《Laravel Composer Package 開發簡明教程》

file

釋出版本並不是那麼隨便的一件事情,錯誤的版本釋出將會給使用者帶來災難性的問題。

正確的 release 的前提是弄清楚語義化版本(Semantic Versioning),它包含 3 個部分:

主版本號:當你做了不相容的 API 修改,
次版本號:當你做了向下相容的功能性新增,
修訂號:當你做了向下相容的問題修正。
所以,請根據你的修改正確的使用版本號。

語義化版本的更多可以去官網(有中文支援)瞭解。

接下來的事情就是推廣,我的一句總結如下:

file

讓真正需要它的或者可能需要它的都知道它的存在,這其中有三個核心:

  1. 真正需要它的:這些人已經有這個需求,但是還沒解決或者沒有很好的解決。
  2. 可能需要它的:正在啟動專案或者將要在專案中用到的一類人。
  3. 知道它的存在:你需要正確的引導到你的專案而不是吹了一大堆後來連個連結都不給。

一些在推廣過程中更細節的點:

file

你需要有自己的品牌,一個易識別的 GitHub ID、微博賬號、微訊號等。

在推廣過程中你會遇到不少噴子或者閒得蛋疼我就是要罵你兩句才舒服的人(根據經驗這類人異常的多,知乎尤甚)。不要和他們噴,切記!

另外就是選對目標,不要跑去什麼媽媽群或者什麼老年人健康中心去推廣你的專案,他們不需要。去 Laravel China 吧,這裡有一群搞 PHP 的小夥伴(當然還搞其它我就不說了)。

然後選擇一個正確的時間點,圖裡我已經列舉,這些時間點大家相對比較活躍,週末都約妹去了你就別浪費時間了。

然後一定要準確並富有表現力的表達,你寫的帖子就一行我反正肯定不看的。

然後你需要有一定的反饋渠道,小專案的話 GitHub issue 就足夠,大專案你搞個 Q 群,論壇都可以。

file

那有了反饋就要關注,每天抽點時間來看看 issue,分類並加入到改進計劃。

請注意,這是最耗時的工作,所以不要影響到你的工作,如果感覺時間已經安排不過來,就找小夥伴一起維護。

如果這個問題很小,那就立即響應修掉再說,比較複雜,就安排到週末,把約妹的時間擠擠。

file

很多時候決定是否要使用你這個專案判斷,除了前面提到的文件與程式碼外,還有以下條件的:最近提交、issue 堆積量。

所以,一個專案的更新活躍度,也是比較重要的。保持專案更新,別人才敢用,不然剛用幾天就進你的坑,結果你半月不給人處理,那人家只能棄坑噴人帶著憤怒離去。

說了這麼多,其實無非就那麼8個步驟,每一步都走穩了,你的專案不會差到哪裡去。

以下是題外話:

最近在做 EasyWeChat 4.0 的開發工作,我希望是月底能 release,如果沒有完成的話你們也不要怪我,因為創業階段事情比較多。

昨天在 overtrue/laravel-wechat 上一個朋友因為沒有細看 README 的說明踩坑了,另外一個熱心網友就去提示他,結果他就噴人家,各種罵,實在慘不忍睹,我後來去看了這哥們的部落格,他自己不認真所致,這位熱心網友並沒有與他爭吵,這裡得點贊,我去解釋了一下,結果提問的哥們又來罵我了。做開源心態很重要,這種情商低的朋友很多,不要跟他們吵,你要想一下,你做為一個能寫開源專案的人,怎麼能跟這種 loser 噴子罵呢是不是,那麼多人圍觀呢,可丟人了。

對了,下一個話題是《基於 Composer 的模組化開發》,敬請期待。

還在等什麼,快去公眾號 “假裝我會寫程式碼” 轉發到朋友圈。

file
file

本作品採用《CC 協議》,轉載必須註明作者和本文連結

相關文章