極狐產品研發團隊代碼審查

1. 你在這里:
2. 極狐 Handbook
3. 極狐研發團隊
4. 極狐產品研發團隊代碼審查

• 總覽
• JH MR 的 review 流程
• Upstream MR 的 review 流程
• Reviewer 和 maintainer
  • 如何成為 maintainer
• Review 第一響應時間
• 盡早溝通
• 提升 code review 的速度
• 主要關注點
• 包容性

總覽

代碼審查（code review）是我們日常開發工作中非常重要的一個環節，每個合并請求（MR）都必須進行 code review。好的 code review 保證了我們在快速迭代的同時，代碼具備足夠的健壯性和可維護性，這是我們確保產品質量的基石。極狐GitLab 的所有 MR，無論是由極狐GitLab 團隊成員還是社區成員編寫，都必須經過 code review 流程，以確保代碼有效、可理解、可維護和安全。

JH MR 的 review 流程

1. 當一個 JH MR 完成準備工作后，請在 MR 中 @ 團隊內部的一位同事從代碼邏輯的角度去 review 這個 MR（如果你不知道找誰合適，請聯系你的 manager）。
2. 請根據 MR 頁面上的代碼所有者（Code Owners）列表添加相關的前端、后端、QA、或者文檔工程師進行 review。
3. 如果 MR 中涉及到了數據庫相關的代碼改動，還需要 @ 毛超(@chaomao) 從數據庫的角度進行 review。
4. MR 被上面兩步的 reviewer approve 后，還需要相關同事從安全的角度進行 review，會自動進入 Triage Ops 安全審查流程，安全 review 完成后會打上 ~"security-review::approved" 的標記。

Upstream MR 的 review 流程

請先閱讀 JiHu Contribution Review Process，了解 GitLab Inc. 關于 JiHu Contribution 的 review 流程。

1. 在創建一個 upstream MR 時，請先把它 標記為 draft 并在 MR 的 description 中 @ 你的 manager，然后進行 peer review，peer review 的流程和 JH MR 的 review 流程保持一致，在 peer review 通過后請在 comment 中留言 LGTM 或者 Looks good 等表示通過。
2. Peer review 完成后，把 MR 標記為 ready 然后讓 GitLab Inc. 的同事去做代碼邏輯的 review，這里有兩種不同的做法：
   • 執行命令 @gitlab-bot ready（如：這個 MR 的做法），這個命令會自動指派一位 reviewer。
   • 如果你非常清楚 GitLab Inc. 的哪位同事比較適合去做 review（比如：他之前就對這個 MR 的背景和上下文比較了解），那你也可以在執行命令 @gitlab-bot ready 的時候直接 @ 他（如：這個 MR 的做法），他就會被直接指派為 reviewer。
   • 對于特別復雜的 MR，可以通過 這個文件 找到 MR 所對應 group 的 EM，然后在 MR 中 @ 這個 EM 讓他來幫忙指派合適的 reviewer。
3. 如果這個 MR 中涉及到了數據庫相關的代碼改動，請 @ reviewer roulette 推薦的 reviewer 來進行數據庫相關的 review，如：，并參考文檔數據庫審查指南。
4. 如果這個 MR 中涉及到了認證、授權相關的代碼改動，請 @ Approvers widge 中列出的一位 reviewer 來從這兩方面進行 review，如：
5. 當上面三步中任意一步的 reviewer approve MR 后，GitLab Inc. security team 還會被自動通知來從安全的角度進行 review（比如：這個 MR）。關于 security review 的更多細節，詳見 此處。

Reviewer 和 maintainer

所有極狐GitLab 的工程師都可以作為 reviewer 對同事和社區貢獻者的 MR 進行 code review，但只有 maintainer 才有權接受 MR。

Maintainer 是 code review 方面的專家，非常了解極狐GitLab 的產品特性、相關代碼和編碼規范，并且有權合并一個或多個極狐GitLab 項目中的 MR。下表列出了當前我們所有的 maintainer：

Area	Maintainers
Backend	Baodong: @icbd on both jihulab.com and gitlab.com Dave: @daveliu on both jihulab.com and gitlab.com Fu: @prajnamas on both jihulab.com and gitlab.com Chao: @chaomao on both jihulab.com and gitlab.com Martin: @mtan-gitlab-cn on jihulab.com and @mtan-gitlab on gitlab.com
Frontend	Jeremy: @jeremywu on jihulab.com and @JeremyWuuuuu on gitlab.com

如何成為 maintainer

快速提升 code review 能力的最佳方式就是盡可能多地參與 MR 的 review，在 MR 中添加你的 review comments，并持續關注這些 comments 的進展直至 MR 被合并或關閉。如果在 code review 的過程中遺漏了一些本應關注的點，請把它們記錄下來以確保在后續 review 別的 MR 時不會出現類似的問題。

成為 maintainer 需具備如下兩個條件：

1. 持續輸出高質量的 code review：你所 review 過的 MR 在經由 maintainer review 時無需再進行較大的代碼改動。
2. 持續輸出高質量的 MR ：你所寫的 MR 在被 reviewer 和 maintainer 進行 review 時無需進行較大的代碼改動。

持續做到上述兩點后，你可以通過如下方式申請成為 maintainer：

1. 創建一個 MR 把自己加入到上面的 maintainer 表格中。
2. 在這個 MR 中以具體示例的方式闡述你為成為 maintainer 已經做好了哪些準備，比如：
   1. 你 review 過哪些對產品帶來顯著改動的 MR ，比如：架構級改動、代碼重構、開發體驗提升等。
   2. 你 review 過哪些提升產品質量的 MR ，如：測試相關、性能相關等。
   3. 你 review 過哪些交付了一個完整功能的 MR 。理想情況下，這些 MR 應該都是通過快速迭代的方式完成的，所以，一個好的 maintainer 需要能夠引導他人把一個較大的 MR 合理地拆分成多個較小的 MR。
3. 把這個 MR assign 給你的 manager 并 @ 其他現有的 maintainer。

批準上述 MR 的流程如下：

1. 這個 MR 會在 open 狀態下保留五個工作日，在此期間如果超過半數以上的現有 maintainer 批準了這個 MR，且沒有任何 blocking concern，那你的 manager 可以合并此 MR，意味著你正式成為了一位新的 maintainer！
2. 如果這個 MR 在五個工作日內沒有得到足夠的批準，并且也沒有任何 blocking concern，那你的 manager 需要在一個新的評論中 @ 現有 maintainer 讓他們盡快提出自己的意見或批準這個 MR，并把這個 MR 再多保留五個工作日。
3. 在額外這五個工作日結束后，任何沒有發表意見的 maintainer 默認對此 MR 持中立態度，如果此時沒有任何 blocking concern，你的 manager 可以直接合并此 MR。
4. 任何非 blocking concern 可以直接作為一個評論提交到這個 MR 中，而對于 blocking concern，maintainer 需要把它單獨發給你的 manager，由你的 manager 跟你溝通并在這個 MR 中添加一個評論來簡要描述這個 blocking concern。
5. 對于任何 blocking concern，提出它的 maintainer 需要和你的 manager 一起制定一個具體的計劃來幫你在今后的開發工作中解決它。
6. 當你的 manager 合并這個 MR 時，需要添加一個評論來對此次批準流程進行一個總結，類似這樣。

在批準成為 maintainer 后，你的 manager 需要：

1. 在 #engineering-internal channel 中正式宣布此事。
2. 把你加入到 #engineering-maintainers channel 中。
3. 把你設置為 https://jihulab.com/gitlab-cn/gitlab 的 maintainer。

Review 第一響應時間

在接收到一個 code review 請求后，應該盡早進行響應，和代碼作者進行溝通，我們認為從收到 MR 到第一次進行響應的時間，不應該超過兩個工作日。

盡早溝通

如果你被分配 review 一個 MR 但卻無法在兩個工作日內開始，你應該在 MR 中留下評論，告知作者你會延遲響應。如果可能，你還應該告知作者何時可以開始，或者幫助他們找到替代 reviewer。

作為 MR 的作者，如果第一響應時間內沒有收到回復，你可以嘗試聯系 reviewer，或者尋找其他 reviewer。

提升 code review 的速度

在提升 code review 的速度方面有以下建議：

• 給你的 MR 添加詳細完整的說明，如果有前端的改動，要包含界面截圖或者視頻演示。
• 這個 MR 能不能再拆分，拆成多個更小單元的 MR 來 review （可以參考這里）
• 添加多位 reviewer，從不同角度進行 review。
• 代碼作者發起一個 review 會議，在會議上更直觀的講解代碼對 review 進度會有很大幫助。

主要關注點

成為 reviewer 是一項具有挑戰的工作，有時需要在開發迭代和質量之間做出平衡。但我們認為對 MR 質量的追求，是我們不能妥協的地方，我們在這里列出一些常見的衡量 MR 質量的關注點，這些并不是全部，但可以作為參考：

• 用戶體驗。代碼改動是否創造了好的用戶體驗？
• 可靠性。代碼可靠嗎？代碼是每次都返回相同的輸出，還是我們引入了很多不可預測的副作用？
• 依賴性和脆弱性。此 MR 中的代碼是否將外部或內部依賴項引入代碼倉庫？請記住，每次有新的依賴項時，我們都要慎重考慮。
• 可維護性。我們是否能夠輕松地對相關代碼進行更改（例如，錯誤修復和需求更改）？是否添加了不必要的代碼？
• 可讀性。一個全新的貢獻者能否理解相關代碼并了解發生了什么？
• 測試。我們幾乎應該為任何改動添加測試。

每個 reviewer 都有自己的 code review 風格，他們有自己的專業知識可以提供，但總的來說，我們希望共同致力于確保極狐GitLab 的高質量標準和為我們的用戶提供更好的服務。

包容性

在極狐GitLab，我們的目標是盡可能地具有包容性，為大家的成長和學習創造空間。 作為 reviewer，鼓勵作者提出問題，并無所畏懼地嘗試他/她認為正確的事情。雖然我們希望在極狐GitLab 中獲得最高質量的代碼，但我們還需要留出空間。在完美主義和推動產品進步之間取得一個巧妙的平衡，這是對 reviewer 一個具有挑戰的地方。

如果你發現自己正在處理一個不符合質量基準的 MR，我們要嘗試幫助作者從中受到啟發，學習經驗，再次嘗試寫出另一個更好的 MR。