Back to Posts

Kubernetes 網站貢獻心得

前言

今年 4 月時,在讀文件的過程中發現了個小錯字,發 PR 後看到 Kubernetes GitHub 的完整流程覺得很酷,就開始參與社群、持續貢獻到現在了。

在研讀完幾份貢獻者說明文件、實際參與過數百個 PR 後,來寫篇中文筆記介紹整套制度流程。

本文將先快速帶過發 PR 後到 merge 經過的階段,接著解釋 標籤的意義,最後統整 社群成員身份 及晉升流程。

發起 Pull Request 後會發生哪些事

在 Kubernetes 的專案中,大多是由 @k8s-ci-robot 負責各項自動化任務的,先來講講行為流程。

在出現新的 Pull Request 時,根據改動的檔案加上不同標籤,例如:

  • 在 k/website 專案中,自動加上 sig/docs
  • 如果更動的行數在 30 - 99 行,標示為 size/M
  • 依照檔案所在的資料夾,加上語言 language/zh 標籤
  • 如果使用者有乖乖簽署貢獻者授權協議,加上必備的 cncf-cla: yes 標籤

在加上標籤後,根據修改到的檔案隨機指派兩名 Reviewer,並告訴使用者在收到 lgtm 後該找哪位 Approver 協助。

@k8s-ci-robot 為 PR 加上 label 分類
@k8s-ci-robot 為 PR 加上 label 分類(k/website#35700

過 10 分鐘後,輪到為每個 PR 建置預覽網站的 Netlify 機器人出場了,會留言告訴我們測試站的連結、失敗的話錯誤原因是什麼。

Netlify 機器人產生好預覽網站
Netlify 機器人產生好預覽網站(k/website#35700

再來只要等搜集到 lgtm + approved 兩個標籤,並且沒有 do-not-merge/holdneeds-rebase 等負面標籤,就會被放進 Merge pool 中。

在 Merge pool 中,為了避免衝突需要等待幾秒到幾分鐘的時間,排到隊後就會自動合併進去啦!

得到 lgtm 及 approved 後自動被合併
得到 lgtm 及 approved 後自動被合併(k/website#34311

標籤的意義

前面快速帶過了整個 Pull Request 從發起到成功合併的流程,再來介紹一下數百個標籤中比較常用的幾個。

正向標籤

lgtm,即 Looks good to me 的意思,任何 Kubernetes 組織成員都可以使用 /lgtm 指令加上此標籤。

LGTM 標籤的意義是「這份程式碼改動看起來不錯」,因此只要檔案有更動,這個標籤就會消失,需要重新用 /lgtm 指令加回來。

得到 lgtm 標籤後更動檔案
得到 lgtm 標籤後更動檔案(k/website#35411

approved,代表這個 PR 的大方向已被核可。

每個檔案所屬的資料夾都有對應的 OWNERS 檔案,記錄著哪些檔案由哪些人擔任 Approver。機器人會確保 PR 修改到的每個檔案都有對應的 Approver 核可,才會加上這個標籤。

lgtm 不同的是,就算檔案被修改過,approved 標籤也不會消失。

使用 approve 指令
使用 approve 指令(k/website#35506

cncf-cla: yes 是第三個不可或缺的標籤,在官方規則下,大家不該 review 沒有這標籤的 PR。

為了確保免於未來潛在的法律爭議,大型專案通常都會要求貢獻者簽署 CLA 授權協議(Contributor License Agreement),只要照著指示一次性的簽署完畢就行了。

CLA 貢獻者授權協議
CLA 貢獻者授權協議(k/website#32897

負面標籤

只要 PR 包含任一個負面標籤,就無法被自動合併。

最常見的是,PR 作者與任何 Kubernetes 成員都可以使用的 do-not-merge/hold

當遇到根本性的錯誤,會用 /hold 來請作者特別注意,常見狀況是 git 操作錯誤,或動到不該動的檔案。

也因為 PR 作者可以自己 /unhold 解除,有時也會被用來作為讓 PR 作者自行控制何時被 merge 的工具,像是最後再次確認有沒有小地方要修改,或是部落格文章希望在哪天發佈。

被 hold 的實際狀況
被 hold 的實際狀況(k/website#34722

在 commit 訊息中包含禁用關鍵字的話,則會出現 do-not-merge/invalid-commit-message

由於專案中已經有 @k8s-ci-robot 來做各種自動化事務了,為了避免意外發生,禁止在 commit 訊息中觸發原先 GitHub 提供的自動化操作。

例如不能在 commit 中寫 Fixes: #xxxThanks @xxx 等,這些要移到 PR 說明欄。

無效的 commit 訊息
無效的 commit 訊息(k/website#34456

needs-rebase,偵測到 merge conflict 時會自動加上此標籤,解決後這個標籤就會自動消失了。

do-not-merge/work-in-progress,只要在標題前面加上 [WIP],或透過 GitHub 介面設定為 Draft PR,就能得到這個標籤了。

分類標籤

最直覺簡單的就屬檔案大小了,計算方式是新增的行數與刪除的行數相加。
這可以幫大家快速判斷需要花多少時間 review,也提醒沒事不要塞一大坨更動,讓 PR 變成過於肥大。
例如最小的 size/XS 代表更動了 0 - 9 行,到修改超過 1000+ 行的 size/XXL

根據不同的面向,會被標上不同的 SIG 特別興趣小組(special interest group)標籤:
sig/docssig/releasesig/security

有些 PR 也會被標上屬於哪個領域:
area/blogarea/web-development

在各語言的資料夾中,會被標上語言標籤,方便在地化翻譯者們過濾:
language/zhlanguage/enlanguage/ko

對於 issue,則是分為不同的種類:
kind/featurekind/bugkind/supportkind/cleanup

社群成員身份

全球 500 萬名 Kubernetes 開發者的數量龐大,光是 k/website 就有 4,100 位貢獻者了,因此 k8s 社群也有一套相對成熟的權限機制。

身份總覽

在開始詳細介紹之前,先讓我快速整理一下 Kubernetes 組織中各身份擁有的大略權限。

(A) 任何人

只要有 GitHub 帳號都可以發 PR、幫忙 review 給意見

(B) Member 組織成員

可以用 /lgtm 指令表示看過、沒問題

也能用 /close/hold/retitle 等指令管理 PR

(C) Reviewer 審核者

在有人發新的 Pull Request 時,bot 會隨機指派 2 位 Reviewer

(D) Approver 批准者

在 PR 被初步 review 過後,會指派 Approver 來做最終確認

在 Approver 確認過大方向無誤後,可以用 /approve 指令核可

(E) Tech Lead / Maintainer / Owner

有專案的管理權限、可以設定 /milestone 指定合併的目標時間

如何開始這場冒險

第一步當然是先熟悉社群、開 issue 發 PR,實際瞭解社群運作。

在找到問題準備修復前,最好可以找 3 - 10 個 PR,看看大家是如何互動的,幫助自己更快融入社群。

Member 組織成員

要成為 Member 的門檻非常低,只要發 5+ 個 PR,並找 2 位 Reviewer 協助背書(sponsor),就可以申請成為組織成員。

申請成為 Kubernetes 組織成員
申請成為 Kubernetes 組織成員(k/org#3440

很酷的一點是,Kubernetes 社群連 GitHub 組織成員都是用 git 管理、自動更新同步的,只要修改對應的 YAML 設定檔,@k8s-ci-robot 就會自動寄發邀請函。

接受邀請成為 Kubernetes 組織成員後,就有了 /lgtm 半通過、/close 關閉 PR、/hold 要求暫緩等大多數的權限,可以隨時參與 PR review。

Reviewer 審核者

如果想成為 Reviewer 身份,規定上的最低限制是成為 Member 至少 3 個月,並且 review 過至少 20 個 PR。

在自認對整個專案程式碼的大架構足夠熟悉後,就可以找 Approver 協助背書,送出申請。

這邊的申請流程跟成為 Member 不同的是,申請的 PR 可以自己開就好,只要約 12 - 48 小時就能成功了。
前面提到想成為 Member 的話需要先開 issue,等過了 3 - 30 天後負責人有空時,才會來批次處理加入申請。或許也跟 Member 身份門檻較低、申請數量過多有關吧。

申請成為 Kubernetes 的 Reviewer
申請成為 Kubernetes 的 Reviewer(k/org#3436

以 k/website 的中文語系為例,每當有新的 language/zh PR 時,就會在 sig-docs-zh-reviews 之中隨機指派兩個人為 PR reviewer,以確保在大家不會累死自己的前提下,每個 PR 都有人能幫忙處理。

這身份承擔的責任在某些時候還蠻重的,但似乎沒有額外授予其他權限,比較像是願意為社群付出、為下一階段鋪路。

Approver 核可者

在擔任 Reviewer 至少 3 個月後,就可以由 Subproject Owner 提名為 Approver 了。

擔任 Approver 必須在技術層面展現合理的判斷,為程式碼品質做高層次的把關,並作為新進貢獻者們的導師。

願意在社群持續貢獻半年一年的志願者們,通常都能順利取得這個身份,相應的 /approve 權限賦予 Approver 們決定 PR 能不能被合併到專案的權力。

Subproject Owner / Tech Lead / Maintainer / Admin

後續身份沒有一套通用的準則,在取得社群內大家的信任後,得到更多的權限也代表著更大的責任。

像是我很好奇那幾位主要貢獻者們到底是怎麼管理時間的,都已經有正職工作了還有辦法投入那麼大的心力在開源貢獻。

後記

我在六月成功加入 Kubernets 組織,因為很喜歡這邊的社群氛圍,期間持續發 PR、幫別人 review,這段期間算是相對積極的貢獻者。

剛成為 Member 才 2 個月的我,在上週被 k/website 最主要的維護者破例提名為 Approver 且通過了,讓我覺得非常驚喜。

因此整理相關資訊分享給身邊的社群朋友們,希望未來有更多人一起加入,期待能做出更多有意義的貢獻。

被提名為中文 Approver
被提名為中文 Approver(k/website#35563

本文同步分享於 TelegramTwitterFacebook, 如果有什麼想法歡迎留言讓我知道。

如果有興趣一起成為 Kubernetes 的貢獻者,歡迎加入 @SeanTalk@CNTUG 群組一同交流。

參考連結

本名韋詠祥,習慣用英文 Sean 暱稱。
自國中開始接觸程式,至今善於組合各種技巧,用來解決生活周遭的問題。
以參加演算法競賽、資安攻防搶旗賽等為樂趣。

Read Previous

來迺陽明交大水所在 陽交校慶系列活動