【融入開源】手把手帶你給知名倉庫貢獻代碼(Element Plus實戰)

前言

為什么有野心有夢想的前端,一定要嘗試去融入開源社區?

因為開源社區內藏著無數的寶藏,真正的寶藏。

最新的工具!對趨勢的把握!親眼見證大佬如何拆解復雜問題!看知名團隊如何在兩難中做出抉擇!解決難題的技巧,迂回兼容的巧妙!
太多太多!
都是日常工作極少有機會面對,更遑論與人探討的。
但是,在開源社區里,你可以向 Evan You 提出疑問,可以向 iamkun 貢獻代碼,可以和更多比你更加優秀的人一起完成一項工作;
那么,是的。
沒有疑問,我們——選擇加入!

第一步:如何篩選倉庫?

要加入社區,但我們應該從哪里開始呢?
我的建議是,先選擇 1~2 你平時工作/學習里最常用到的,且還不是特別穩定的庫,如果是 alphabeta 版本優佳。

  • 經常用到。意味著你會更懂它,也更容易發現問題。
  • 版本還不穩定。意味著問題更多也更容易出現容易修復的問題。(對于咱初入者而言,這很重要)
  • Star較多。Star多意味著這個庫有一定影響力,被很多人用,更容易發現問題;
  • 維護頻繁。維護頻繁,意味著你的PR會在短周期內被處理,這對維持積極性而言非常重要。

以我個人情況為例,我當前的主要技術棧以 vue3.x 為主,配合 Element Plus , vite , vite-press 等,按上面提到的幾點綜合考慮,我會選擇這個庫作為我近期 學習 的主要目標:

  • Element Plus (版本:1.2.0-beta.5)
  • vitepress (版本:0.20.2)

這兩個庫基本都充分符合上面我列舉的幾個要點。

image

Element Plus 為例:

  • 12.8K Star (超多點贊)
  • 2.2K Fork (被2.2K人次拉到自己的倉庫)
  • 236K+ Download /Month (每月23萬次+下載 )
  • 300+ Open Issues (至少有300個正在討論未被關掉的問題)
  • 90+ Open PullRequest (90+個還未被合并的合并請求)
  • 170+ Commit Last Month (近1個月有170+ 次提交)
  • 著名UI庫 ElementUI 2.x正統續作,專業性上不用擔心,能學到更多東西和規范。
  • 我每天 8小時 用到它,更容易發現問題。

就我個人而言,這絕對是當前最最最適合我進行 嘗試貢獻 的庫之一了。
如果按以上思路,最適合你進行 嘗試 的庫是什么呢?
如果也是 Element Plus,那也太有緣分了,可以多交流????。

第二步: 如何尋找修改點 ?

一般而言,修改點有兩種來源:

  • 在倉庫的 issues列表 里尋找適合自己的問題。
  • 你自己在使用過程中遇到的問題。

a. 如何在 issues列表 淘問題?

Issues 可以被翻譯成 問題。通常被用來 求助報告問題,尋求新特性等。

在項目的 issues列表 找適合自己的問題,絕對不是漫無目的的憑運氣亂撞。而是有技巧的

首先,篩選 Open 狀態的問題

Issue 分為 OpenClosed 兩種狀態。
Closed 狀態的問題,要么已經被官方判定為無效issue,要么已經解決
因此,對于我們而言,完全可以保持 issue 列表頁的搜索框里常年保持以下篩選條件:

 is:open 

其次,學會通過 Label 過濾

Label 的含義是標簽,通常開源庫的 維護者 會通過給不同類別的問題打不同的 Label 來更便捷的管理。

Element Plus 為例,它擁有72種不同的 Label:

image

有的表明 issue的種類 ,有點表明 涉及的組件,有的表明 它來自社區貢獻,等等等等。但最最最重要的卻是下面這兩個tag:

  • PR welcome (歡迎提交PR)
  • Good for new contributor (適合新人貢獻)

因此,我們可以直接選中二者之一,開始我們的 issue 探索之旅。

image

就像這樣進行篩選。????
然后,找到自己有思路的問題。

不要害怕英語,使用瀏覽器翻譯或翻譯插件!如果你英語特別好,那當我沒說。

經過5分鐘 中英結合 的搜尋,我鎖定了一個問題:

image

"級聯組件: 請添加一個選項,使篩選(搜索)不區分大小寫。"

確認過眼神,是我能力范圍內的問題。

點進去,經過對 Label 的判斷,此 Issue 歡迎提交PR,且有 Feature Request(特性需求)。

因此,我們完全可以大膽地進行開發!

ok,以此為例,我們了解了 如何通過issue列表 找到適合我們的問題。

b. 自己發現的問題怎么辦?

發現問題千萬別急著提PR!先去 issue 列表搜一下!

某個問題,你是 第一個發現者 的概率其實并不大,因此對于咱們普通開發者而言,遇到的大多數問題,應該都能在 issue 列表里找到答案。
如果翻遍 issue 列表都沒找到同病相憐者,恭喜你!你發現了一個新問題!
如果你經過研究,發現自己就能解決問題,那可太好了。
不過我推薦你還是要先建一個 issue 來描述你的問題,后續再解決這個 issue
這樣,后來者可以發現這個問題已經被解決,也可以進行更詳細的問題記錄與跟蹤。

image

注: 提ISSUE時不僅要遵循倉庫的規范,請一定提供最小可復現實例

jsfiddle, codepen, codesandbox 都是極好的 最小可復現實例 工具。

比方說

我某天在工作時發現 El-Table 當設置了 tooltipEffect="light" 屬性后,帶有 show-overflow-tooltip 屬性的列,在文本超長時,彈出的 tool-tip 樣式存在1px的錯位。

長這樣:

image

在粗略看了一遍源碼之后,我立刻意識到:
這bug我能改!

于是我利用工作之余的時間創建了 issue 并提交了解決此 issuePull Request

那么?

什么是 Pull Request 呢?又該如何提交?繼續向下看吧。

第三步: 怎么fork倉庫?

在進行代碼修改之前,我們得先了解一下 github 開源倉庫代碼提交的基本模式: fork => Pull Request 模式。

image

通常情況下,你要向某個開源倉庫貢獻自己的代碼(以 element-plus 為例):

  1. Fork!

element-plus 主倉庫 fork 一份代碼到你主頁的 xxx/element-plus 倉庫。(可以理解從 element-plus 復制了一份一模一樣的代碼)

  1. Commit!

在自己的倉庫里修改 bug,并提交 commit 到自己的 xxx/element-plus 倉庫里。

  1. PR!

element-plus 主倉庫提起 Pull Request ,申請合入。(把自己的 commit 擇出來,寄給主倉庫的維護者,并告知他們你期望自己的代碼能被合入到主倉庫)

  1. NICE!

你的代碼被合入,等待發版。

站在一個貢獻者角度來看,貢獻代碼只需要按上面的步驟一步步執行即可。

那么,我們應該怎么 fork 代碼呢?很簡單,一鍵完成。

image

對,你只需要在 主倉庫 的右上角輕輕點一下鼠標,就能完成 fork
很快,你的個人主頁里,就會多出一個倉庫:

image

沒錯,這就是你成功fork到的倉庫,后續你的代碼提交和推送,都需要在這個倉庫里完成。

第四步:如何找到倉庫的調試方法?

說到修復 bug ,那么 調試 一定是必不可少的一部,畢竟我們都只是凡人。

但是,我們所貢獻的很多代碼都不是 應用APP,而更大可能是一些提供 能力 的類庫,如:
UI庫調試工具腳本等等...
這樣一來,我們就必須找到 如何高效調試 的方法。

方法1: 看 Contribute.md

大部分的倉庫,都有專門寫給貢獻者看的貢獻指南,它們的名字不一而足,有的叫 CONTRIBUTE.md,有的叫 DEV.md ,也有的叫 DEV_FAQ.md
通常這個文檔都會告訴你應該"如何啟動項目",以及"如何調試項目"。
element-plus 為例,它的 開發者指南 就名叫 DEV_FAQ.md
并在這個 .md 文件中介紹了三件事:

  1. 使用 pnpm i 安裝依賴
  2. 使用 pnpm link 方式調試
  3. 別在 themescss 文件里寫中文注釋。
image

"開發者指南"的詳盡指南需要碰運氣,而我們必須通過其他途徑了解項目的技能能力,那我們應該怎么做呢?

方法2:看 package.json 里的 scripts

眾所周知,前端項目 package.json 里的 scripts 通常是整個項目各類腳本的 控制中心。包含但不限于:
commit 規范調試命令構建命令文檔構建版本升級... 等等,各種各樣的能力都在此匯聚。

可以說,了解了 scripts,也就了解了項目在 開發過程中 究竟能做哪些事。

element-plus 為例,讓我們快速掃一眼它的 scripts 吧!

image

經過簡單一掃,發現了一個可能會對我們調試非常有用的 腳本:

pnpm run dev

執行上面的命令,就能快速啟動一個3000端口的服務,打開時會發現加載了幾個 element-plus 組件。

而此 調試頁面的入口 在這里:

play/main.ts

第五步:編寫代碼,修復BUG!

這一節,我本來想 略過 的。
畢竟:

改bug嘛!這誰不會啊?

image

好了,玩笑就開到這。
以我改的這個 issue #4697 為例。
為了修復這個bug,我總共做了一件事:

image

????沒錯,一共就只刪了一行代碼而已。

第六步:按規范提交代碼

看到這里,我先假設你已經完全"修復了 bug" 或 "實現了特性"。

那么,該如何提交代碼呢?

1. 手動填寫 commit-msg

不同的 項目 在細節上通常會有不同的要求。
commit 規范 通常情況下都是要求遵循 conventionalcommits 規范的。
# conventionalcommits 鏈接
conventionalcommits 規范,簡單概括,其格式大抵如下:

# 類別 影響范圍 : 簡單描述
<type>[optional scope]: <description>
# 詳細描述
[optional body]
# 一些關聯信息,如關聯issue
[optional footer(s)]

舉個栗子

# 類別 + 簡單描述
feat: allow provided config object to extend other configs
# 類別 + 簡單描述 + 不兼容更新聲明(感嘆號)
feat!: send an email to the customer when a product is shipped
# 類別 + 簡單描述 + 不兼容更新聲明(感嘆號)+ 影響范圍(括號內的內容)
feat(api)!: send an email to the customer when a product is shipped

更具體的描述大家可以點擊上面的鏈接進行更加細致的學習,此處不再過多介紹。

2. 通過工具交互式提交

此方案不是方案1的替代式方案,而是某些倉庫強制要求的 commit 規范!

熟悉開源社區的朋友可能會發現,越來越多的開源項目都開始 直接或間接 的依賴一款叫 commitizen (# 地址) 的 npm 包或者它的間接產物。
比如:element-plusyarn 就直接使用了它

image

這個工具的作用,便是"交互式"地"規范你的提交記錄"。

ok,明白了這點,我們便可以"交互式"地開始提交我們的 commit-msg

element-plus 的提交過程為例,具體過程如下:

yarn cz
? Select the type of change that you're committing:
# 然后就會交互式地讓你選擇類別,包括:特性/feat,fix/修復,docs/文檔,style/樣式 等等
# 根據你的提交內容,選擇合適的類別,比如你修復了一個bug,則通過移動光標選擇 fix
> fix
? What is the scope of this change (e.g. component or file name): 
# 你的修改范圍是什么?比如如果你修改了組件,就輸入:components
> components
? Write a short, imperative tense description of the change (max 83 chars):
# 請您填寫一個簡短的祈使句來描述你做的變更。
# 祈使句的意思,如:讓表格支持變形;修復 #0001;
# 以上面 “刪掉一行代碼” 的修復為例
> fix #4697 
? Provide a longer description of the change: (press enter to skip)
# 提供一個詳細的描述
# 可以跳過
? Are there any breaking changes?
# 有不兼容的變更嗎?
# N沒有/Y有
? Does this change affect any open issues?
# 有什么相關的open狀態的issue嗎?
# 有點話Y,沒有N

然后還會觸發一些文件格式規范的流程,接著,你的commit才能成功。

這樣做的好處,在于后續element-plus官方可以通過commit記錄生成每個版本的CHANGELOG

第七步:全部通過單元測試

其實,這一步理論上來說,寫在 commit 之前更加妥帖,畢竟改完代碼你不跑跑測試用例,簡直有點過分自信了。

如果你的修改是 bug-fix ,你只要正常通過 yarn test 問題通常就不大了。

但如果你的修改是新特性,那你可能還得自行添加一些用例。

比如,你添加的特性是:

增加一個 prop,當它為 true 時,按鈕變成彩虹色

那你就必須增加一個測試用例,確保當它為 true 的時候,它真的已經變成了彩虹色,不然萬一后續有哪個兄弟新增了一個特性或修復了一個bug,導致你的 按鈕彩虹色 功能失效了,直到版本發布都不會有人發現。

這會直接導致某些特性在生產環境產生嚴重作用。

因此,跑用例寫用例是每個想參與開源的朋友,必須養成的意識。

第八步:提交PR!

8.1 把代碼推送到你 fork 出來的分支里去吧

# 假設你在 fix-4697 這個分支上修復bug
git push  origin fix-4697

8.2 生成PR

image

在你 fork 出來的項目里,打開 Pull Request tab,然后點擊最右邊綠色的 New Pull Request 按鈕。
image

瀏覽你的 merge 信息,確認它們是否正是你想要提交的內容。

第九步:靜候佳音

當你的PR被創建之后,不要焦慮,你能做的可能只有等待。

也許你會突然收到 github 站內信,你的 PR 被成功 合入,那就表示,從這一刻開始,你成為了這個 開源倉庫 的貢獻者之一。

主倉庫insight標簽里點擊Contributors,開始嘗試尋找你的名字吧!

image

現在開始,你可能已經算是這個開源倉庫的貢獻者之一了。

關于我

我是專注前端,專注vue,專注Element等框架的“前端要摸魚”。
我的微公信眾上號也叫 前端要摸魚

獲取最實用的前端技巧,每天快樂摸魚,早早下班

最后編輯于
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容