返回文章列表
玄貓（BlackCat）

GitHub Pull Request 程式碼協作藝術

本文探討 GitHub Pull Request (PR) 的使用技巧與最佳實務，涵蓋從提交變更、撰寫 PR 描述到程式碼審查的完整流程，並分享如何運用 Draft PR、程式碼比較模式、合併選項等功能提升團隊協作效率與程式碼品質。同時，文章也介紹了 GitHub Actions、CODEOWNERS、Issue 和

軟體開發 版本控制
GitHub Pull Request 程式碼審查 協作 Git DevOps

GitHub Pull Request (PR) 是現代軟體開發協作的根本，有效運用 PR 機制能大幅提升團隊效率與程式碼品質。建立 PR 的流程始於提交清晰的 commit message，簡述變更內容並詳述修改原因。接著，在 GitHub 儲存函式庫中建立 PR，選擇欲合併的分支，撰寫簡明扼要的標題和詳細的描述，並指定審閱者。審閱階段可選擇統一或分割模式比較程式碼差異，仔細檢查每一處修改，確保邏輯正確、風格一致且無新錯誤。

Draft PR 功能允許在程式碼尚未完成時建立 PR，方便進行中間審閱和團隊協作，及早發現潛在問題並確保程式碼符合團隊標準。GitHub 提供三種合併選項：建立合併提交、壓縮並合併以及變基並合併，團隊可依 Git 歷史記錄管理策略選擇。程式碼審查時，應保持客觀、提供建設性回饋、檢查可讀性及測試覆寫率，確保程式碼易於理解、符合規範且經過充分測試。

def add(a, b):
    """
    將兩個數字相加。

    Args:
        a: 第一個數字。
        b: 第二個數字。

    Returns:
        兩個數字的和。
    """
    return a + b

# 測試案例
def test_add():
    assert add(2, 3) == 5
    assert add(-1, 1) == 0
    assert add(0, 0) == 0

內容解密：

這段程式碼定義了一個名為 add 的函式，它接受兩個引數 a 和 b，並傳回它們的和。函式內部使用 return 陳述式傳回計算結果。測試案例 test_add 使用 assert 陳述式驗證函式在不同輸入下的正確性，確保函式功能符合預期。

name: Python CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9", "3.10"]

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Run tests
      run: pytest

內容解密：

這個 GitHub Actions 工作流程定義了一個名為 Python CI 的作業，它會在每次推播到 main 分支或建立 main 分支的 PR 時觸發。作業在 ubuntu-latest 環境中執行，並使用策略矩陣在 Python 3.9 和 3.10 版本上測試程式碼。步驟包括：使用 actions/checkout@v3 簽出程式碼，設定 Python 環境，安裝依賴項，最後使用 pytest 執行測試。

GitHub 提供的 CODEOWNERS 檔案可自動指派審閱者並明確程式碼所有權，提升審查效率與程式碼維護效率。Issue 和 PR 範本則能引導貢獻者提供完整資訊，確保問題報告和 PR 符合專案標準，提升協作品質。善用 GitHub PR 與相關工具，能有效提升團隊協作效率、程式碼品質及專案管理效率，是現代軟體開發不可或缺的技能。

深入 GitHub 協作：精通 Pull Request 的藝術

身為玄貓，我深刻體會到程式碼協作的重要性。而 GitHub 的 Pull Request (PR) 機制正是現代軟體開發中不可或缺的一環。它不僅簡化了程式碼審查流程，更提升了團隊協作效率。在這篇文章中，玄貓將分享使用 GitHub PR 的經驗與技巧，希望能幫助你更好地掌握這個強大的工具。

從 Commit 到 Pull Request：程式碼旅程的起點

在提交程式碼變更之前，仔細思考並撰寫清晰的 commit message 至關重要。這個 message 將成為 Git 的提交記錄，也將在 PR 中扮演重要的角色。玄貓通常會使用簡潔的標題概括變更內容，並在正文中詳細描述修改的原因和影響。

提交變更後，GitHub 儲存函式庫的首頁通常會顯示建立 PR 的提示。你也可以點選 Pull requests 標籤下的 New pull request 按鈕來手動建立 PR。

圖表翻譯： 此圖示展示了從提交變更到建立 Pull Request 的流程。首先，變更被提交到儲存函式庫，接著系統會提示建立 PR，或者你可以手動建立。無論哪種方式，都需要選擇合適的分支來進行比較，最後完成 PR 的建立。

審閱變更：洞察程式碼的細節

GitHub 提供了兩種程式碼差異比較模式：統一模式和分割模式。統一模式將差異內嵌在每一行程式碼中，而分割模式則將原始程式碼和修改後的程式碼並排顯示，方便更清晰地比較。

圖表翻譯： 此圖表說明瞭 GitHub 提供的兩種程式碼比較模式。開發者可以根據需求選擇適合的模式來審閱程式碼變更。

玄貓個人偏好分割模式，因為它能更直觀地呈現程式碼的變化。在審閱程式碼時，玄貓會仔細檢查每一處修改，確保程式碼的邏輯正確、風格一致，並且沒有引入新的錯誤。

撰寫 Pull Request：溝通的橋樑

一個好的 PR 應該包含清晰的標題、詳細的描述和指定的審閱者。標題應簡潔明瞭地概括 PR 的目的，描述則需詳細說明變更的內容、原因和影響。

撰寫 PR 描述時，玄貓會考慮目標讀者，並根據他們的理解程度調整描述的詳細程度。如果審閱者是特定的人，玄貓可能會省略一些共同理解的背景資訊。

Draft Pull Request：迭代開發的利器

除了標準的 PR 之外，GitHub 還提供了Draft PR 功能。Draft PR 允許你在程式碼尚未完成時就建立 PR，方便進行中間審閱和團隊協作。

圖表翻譯： 此圖示展示瞭如何利用 Draft PR 進行迭代開發。你可以在開發初期就建立 Draft PR，並持續更新，直到功能完成後再轉為正式 PR。

透過 Draft PR，團隊成員可以提前瞭解正在進行的工作，並提供寶貴的回饋。這種機制大大提高了協作效率，並確保最終的程式碼品質。

程式碼審查的最佳實踐

在進行程式碼審查時，玄貓會遵循以下幾個最佳實踐：

  1. 保持客觀: 審查程式碼時，應專注於程式碼本身，而不是作者。
  2. 提供建設性回饋: 給出具體的建議和改進方向，而不是簡單地指出問題。
  3. 檢查可讀性: 確保程式碼易於理解，並且遵循團隊的編碼規範。
  4. 測試覆寫率: 檢查相關的測試是否已更新，以覆寫新的程式碼變更。
def add_numbers(a, b):
    """簡單的加法函式"""
    return a + b

# 測試案例
def test_add_numbers():
    assert add_numbers(2, 3) == 5
    assert add_numbers(-1, 1) == 0
    assert add_numbers(0, 0) == 0

內容解密：

上述 Python 程式碼展示了一個簡單的加法函式及其對應的測試案例。函式 add_numbers 接受兩個引數並傳回它們的和。測試案例 test_add_numbers 使用斷言來驗證函式在不同輸入下的正確性。這種測試驅動的方法有助於確保程式碼的正確性和可靠性。

掌握 GitHub Pull Request 的藝術，不僅能提升個人開發效率，更能促進團隊協作。透過清晰的 commit message、有效的程式碼審查以及適時的 Draft PR，你可以讓程式碼協作變得更加順暢。希望玄貓分享的經驗和技巧，能幫助你在 GitHub 的協作之旅中走得更遠。

GitHub 協作與專案管理深度解析

深入理解 GitHub Pull Request

在軟體開發的世界中，GitHub Pull Request（PR）是團隊協作的核心環節。它不僅是程式碼審查的基礎，更是確保程式碼品質和促進團隊溝通的重要工具。

Draft PR：早期回饋與協作

使用 Draft PR 可以在早期階段就與團隊成員分享程式碼進度，取得寶貴的回饋。這種做法有助於及早發現潛在問題，並確保程式碼符合團隊的品質標準。

圖表翻譯： 上圖展示了 Draft PR 的工作流程，從建立到最終合併的每個階段都清晰呈現。這種視覺化的流程圖幫助團隊更好地理解 PR 的生命週期。

合併選項：Git 歷史的管理藝術

GitHub 提供了三種合併選項：建立合併提交、壓縮並合併以及變基並合併。選擇合適的合併方式取決於團隊對 Git 歷史記錄的管理策略。

圖表翻譯： 此圖示闡述了 GitHub 提供的三種合併選項。每種選項都有其特定的使用場景和優缺點，團隊應根據實際需求選擇最合適的方式。

Pull Request 審閱的深度解析

在進行 PR 審閱時，審閱者應關注多個方面，包括程式碼的正確性、可讀性、效能、安全性和測試覆寫率。

程式碼審閱的最佳實踐

  1. 及時回饋： 儘快提供回饋，保持開發的節奏。
  2. 注重細節： 程式碼是團隊的共同資產，審查時應仔細檢查每個細節。
  3. 清晰溝通： 使用 Markdown 格式撰寫清晰、結構化的回饋，避免歧義。
  4. 積極肯定： 多使用正面肯定和建設性回饋，營造友善的審查氛圍。

GitHub Projects：專案管理的強大工具

GitHub Projects 提供了多種視覺化工具，如 Kanban 看板和表格檢視，幫助團隊更有效地管理 Issues、Pull Requests 和專案進度。

Kanban 看板的使用

Kanban 看板可以視覺化團隊的工作流程，自訂欄位如「待辦」、「進行中」和「已完成」，透過拖曳卡片管理任務進度。

表格檢視的優勢

表格檢視提供了更詳細的資訊，如任務的指派者、里程碑和截止日期，確保團隊成員目標一致，協同合作。

程式碼範例與內容解密

以下是一個簡單的 Python 函式範例，用於向指定的人打招呼：

def greet(name):
    """
    向指定的人打招呼。
    
    Args:
    name (str): 被問候者的名字
    
    Returns:
    str: 包含問候語的字串
    """
    return f"Hello, {name}!"

print(greet("World"))

內容解密：

這段程式碼定義了一個名為 greet 的函式，它接受一個引數 name，並傳回一個包含問候語的字串。函式內部使用 f-string 格式化字串，將 name 的值嵌入到問候語中。最後，程式碼呼叫 greet 函式，並將 “World” 作為引數傳入，將結果印到螢幕上。

GitHub Codespaces：雲端開發環境的革新

GitHub Codespaces 提供可完全設定的雲端開發環境，簡化了團隊協作和 DevOps 實務。其主要功能包括快速啟動和統一工作空間、協作和提取請求整合，以及安全與隔離的環境。

圖表翻譯： 上圖展示了開發者與 GitHub Codespaces 的互動流程，突顯了其快速啟動和便捷使用的特性。

GitHub Discussions：社群互動的樞紐

GitHub Discussions 提供了一個專門的空間，讓開發者、貢獻者和使用者進行問答、分享想法和討論。它促進了知識分享和社群互動，有助於保持 Issues 區段的整潔和重點。

圖表翻譯： 上圖簡潔地展示了 GitHub Discussions 如何促進知識分享和問題解決，增強了社群互動。

規則集與程式碼品質管理

規則集允許各種設定。它們可以僅應用於特定分支，或者管理員可以被授權繞過它們。

圖表翻譯： 此圖示展示了分支規則的設定流程。首先決定是否針對特定分支套用規則，如果是，則應用規則；如果否，則設定全域規則。無論是哪種情況，最終都會進入強制執行策略的階段，以確保程式碼品質。

分支規則的主要優點之一是強制執行程式碼審查。透過要求 Pull Request 在合併之前獲得一定數量的批准，團隊可以確保每個變更都經過仔細檢查和驗證。這種同行審查流程不僅提高了程式碼品質，還在團隊成員之間促進了知識分享和協作。

狀態檢查是分支規則的另一個關鍵部分。這些檢查可以包括自動化測試、程式碼檢查結果或任何其他型別的自動化流程，用於驗證程式碼的品質和功能。透過要求在合併之前透過這些檢查，團隊可以防止錯誤和問題進入主要程式碼函式庫，從而保持高標準的程式碼品質。

分支規則是 GitHub 中用於保障程式碼品質和執行工作流程紀律的基本設定。它們使團隊能夠自動化和強制執行開發流程的關鍵環節，與 DevOps 原則相一致。透過利用分支規則，團隊可以確保其程式碼函式庫保持穩定、安全和一致，從而支援在協作環境中交付高品質的軟體。這使得分支規則成為現代軟體開發中的重要元素，也是 DevOps 工具包中的寶貴資產。

CODEOWNERS：簡化審查和所有權

GitHub 中的 CODEOWNERS 檔案是一個簡單但功能強大的工具，用於自動將審閱者指派給 Pull Request，並闡明特定程式碼區域的所有權。此檔案放置在儲存函式庫的根目錄、docs/ 或 .github/ 目錄中，列出個人或團隊以及檔案模式。當對符合這些模式的檔案進行變更時，系統會請求指定的程式碼所有者進行審查。

# 這是一個範例 CODEOWNERS 檔案
# 以 '#' 開頭的行會被忽略。

# 將 @my-org/platform-team 指派給 platform 目錄下的變更
/platform/ @my-org/platform-team

# 將 @user1 指派給 docs 目錄下的任何變更
/docs/ @user1

內容解密：

以上程式碼片段展示了 CODEOWNERS 檔案的範例。它定義了哪些團隊或個人負責審查特定目錄下的程式碼變更。例如，platform 目錄下的任何變更都會自動指派給 @my-org/platform-team 進行審查，而 docs 目錄下的變更則會指派給 @user1。這種機制簡化了審查流程，並明確了程式碼所有權。

使用 CODEOWNERS 檔案的好處包括：

  • 自動審閱者指派：簡化 Pull Request 流程，自動指派正確的審閱者，確保變更由適當的專家檢查。
  • 明確所有權：闡明誰負責程式碼函式庫的特定部分，有助於更快的決策和更有效的維護。

CODEOWNERS 的這一方面尤其重要，因為它與佈署安全直接相關。在 CI/CD 常態化的環境中，確保只有經過良好審查和批准的程式碼才能佈署至關重要。這為佈署流程增加了一層安全性和效率，體現了有效 DevOps 實踐的核心——預防性和主動性原則。

Issue 和 Pull Request 範本

GitHub 中的範本可增強協作並在專案管理的各個方面保持一致性。Issue 範本引導貢獻者建立詳細與結構化的問題報告。透過為不同型別的問題（錯誤報告、功能請求等）提供特定範本，您可以確保包含所有必要資訊，從而更容易理解和更快地解決問題。

Pull Request 範本確保每個 Pull Request 符合專案的標準和要求。這些範本通常包括核對清單、描述變更的區段、參考相關 Issues 以及任何其他注意事項。這種標準化簡化了審查流程並提高了貢獻的品質。

這些組成部分在塑造一個組織良好、易於存取與對貢獻者友好的 GitHub 儲存函式庫方面發揮著至關重要的作用。透過實施這些標準基礎檔案和範本，您為協作和專案管理奠定了堅實的基礎，與 DevOps 和開源文化的最佳實踐產生共鳴。

GitHub Actions 與 CI/CD 自動化

GitHub Actions 作為 GitHub 原生的 CI/CD 平台，徹底改變了軟體開發和佈署流程的自動化方式。它允許開發者直接在 GitHub 儲存函式庫中建立、管理和執行工作流程，提供簡潔明瞭的操作體驗。

@startuml
skinparam backgroundColor #FEFEFE

title GitHub Pull Request 程式碼協作藝術

|開發者|
start
:提交程式碼;
:推送到 Git;

|CI 系統|
:觸發建置;
:執行單元測試;
:程式碼品質檢查;

if (測試通過?) then (是)
    :建置容器映像;
    :推送到 Registry;
else (否)
    :通知開發者;
    stop
endif

|CD 系統|
:部署到測試環境;
:執行整合測試;

if (驗證通過?) then (是)
    :部署到生產環境;
    :健康檢查;
    :完成部署;
else (否)
    :回滾變更;
endif

stop

@enduml

圖表翻譯： 此圖示展示了 GitHub Actions 的核心結構，由工作流程、作業、步驟和動作組成。每個步驟可以執行一個或多個動作，多個步驟組成一個作業，而多個作業則構成一個完整的工作流程。這種結構使得自動化流程更加模組化和可管理。

工作流程結構解析

GitHub 工作流程是現代軟體開發自動化的典範，它從根本上改變了開發者處理 CI/CD 流程的方式。一個工作流程可以分解成以下幾個關鍵元素：

  • 工作流程 (Workflow)：自動化的支柱，定義整個流程。
  • 作業 (Job)：在相同環境中執行的一組步驟。
  • 步驟 (Step)：工作流程的最小單位，每個步驟代表一個單獨的任務。
  • 動作 (Action)：可重複使用的單元，組合成步驟來執行特定任務。

工作流程：自動化框架

GitHub Actions 的核心概念是工作流程。它不僅僅是一系列任務，而是一組自動化、結構化與高度可定製的程式，所有程式都定義在一個 YAML 檔案中。此檔案位於 GitHub 儲存函式庫的 .github/workflows 目錄中，是自動化策略的藍圖。在每個 GitHub 事件（例如推播或提取請求）發生時，這些工作流程就會啟動，使自動化流程得以運作。

Webhook 事件觸發器

GitHub Actions 工作流程可以由各種事件型別觸發，每個事件觸發不同的自動化序列，這些序列定義在 YAML 檔案中。以下是一些典型的觸發事件：

  • 提取請求操作： 當提取請求被開啟、更新、合併或關閉時，工作流程可以被設定為觸發。這允許自動化測試、程式碼審查和合併衝突檢查，確保在整合到主分支之前驗證變更。
  • 議題操作： 與提取請求類別似，工作流程可以對議題活動做出反應，例如建立、指派、標記和關閉。這非常適合自動議題回覆範本。

以下是一個典型的 Node.js 應用程式 CI 工作流程範例，觸發條件為每次推播至主分支和提取請求：

name: Node.js CI
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x, 18.x]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: tsc
      - run: node dist/test

內容解密：

這個工作流程定義了一個名為 Node.js CI 的作業，它會在 ubuntu-latest 環境中執行。策略矩陣允許在不同 Node.js 版本 (16.x 和 18.x) 上測試程式碼。步驟包括：使用 actions/checkout@v3 簽出程式碼，設定 Node.js 環境，使用 npm 安裝依賴項，編譯 TypeScript 程式碼，最後執行測試。這個範例展示了 GitHub Actions 的簡潔性和靈活性。透過簡單的 YAML 設定，即可自動化構建、測試和佈署流程，從而提高開發效率和程式碼品質。