AI App 開發← 返回第 7 週課綱

第 07 課 ／ 讓修改可以被審查

Git 協作與
自動化檢查

把第六週的功能分支送到 GitHub，建立 PR，請同學審查，回應意見並修正，再合併到主分支。用 SwiftFormat 與 GitHub Actions，讓同一套檢查隨每次更新執行。

本週協作流程

功能分支 → Commit 與 Push → 建立 PR → Review 與 CI → 修正並再次 Push → Merge → 更新本機主分支

每次追加 commit 都更新同一個 PR；審查者與自動檢查要確認最新一版修改。

01 ／ 分支與遠端

確認版本，再 Push 功能分支

沿用第六週已有的功能分支；若開始另一項改動，從乾淨且已更新的主分支建立新分支。將範例的檔案路徑、分支及 origin 換成專案實際值。

git status
git branch
git remote -v
# 若是新任務，先從主分支開始
git switch main
git pull --ff-only
git switch -c feature/feedback-settings
# 完成修改並驗證後
git diff
git add path/to/changed-file
git diff --staged
git commit -m "Improve settings from user feedback"
git push -u origin feature/feedback-settings

若分支已存在，使用 git switch feature/feedback-settings，從差異檢查接續操作。--ff-only 無法更新時，先查看本機與遠端差異，再決定處理方式。

02 ／ 建立 PR

說清楚問題、修改與驗證

  1. 選擇合併方向

    在 GitHub repository 開啟 Pull requests → New pull request，或使用 Compare & pull request。base 是要接收修改的主分支，compare 是你的功能分支。

  2. 閱讀整份差異

    確認檔案與 commit 範圍符合任務；移除不相關的改動。尚未準備好時建立 Draft PR，完成後再標示可審查。

  3. 填寫內容並邀請 Reviewer

    標題描述成果，內文說明原因、行為變化與證據。邀請同學 Review；私人 repository 需先由擁有者提供必要存取權。

問題：用戶無法理解「只顯示未完成」設定。
修改：調整文案，加入設定狀態與空白清單說明。
驗證：建置通過；在 iPhone 切換設定並重新開啟 App。
證據：操作畫面／測試結果。
限制：尚未驗證其他裝置尺寸。
請協助審查：設定值的保存與清單更新是否一致。

若已安裝並登入 GitHub CLI，也可用 gh pr create --base main --head feature/feedback-settings。Git 的 Push 是同步 commit；建立 PR 是 GitHub 上提出合併與審查的步驟。

03 ／ Review 與回應

審查行為、資料流與證據

Reviewer

先看 PR 目的，再在 Files changed 逐段閱讀差異。

檢查設定預設值、保存方式、狀態管理、空白與失敗情境，以及驗證是否涵蓋改動。

意見寫出「位置、問題、觸發情境、建議驗證」。提交 Comment、Approve 或 Request changes，讓作者知道審查結論。

作者

逐項回應意見，說明接受、修改或採取其他做法的理由。

請 Agent 處理選定意見，自己審查 diff、建置與操作，再追加 commit 並 Push 同一分支。

PR 會更新；請 Reviewer 看最新修改，確認討論已處理。

04 ／ 合併與同步

完成 Review 與檢查，再 Merge

  1. 確認最新版本

    檢查 Review、未處理意見與 CI 結果，確認是目前最新 commit。若有衝突，理解雙方改動後修正，再重新驗證與審查。

  2. 在 PR 合併

    依專案約定選擇 Merge commit、Squash 或 Rebase merge。課堂可用 Squash 將此 PR 的修改整理成一個 commit；先確認 base 分支與結果。

  3. 更新本機與驗證

    切回主分支並 Pull，重新建置與操作，確認本機取得 GitHub 的合併結果。完成後才依需要刪除功能分支。

git status
git switch main
git pull --ff-only
git log --oneline -5

本課在 GitHub PR 完成合併，以保留 Review 與 Checks 紀錄。Sublime Merge 可用來切回 main、Pull 與查看 commit graph。

05 ／ SwiftFormat

在本機與 CI 使用相同格式規則

本課使用 nicklockwood／SwiftFormat。先在小範圍試跑，查看差異，再把專案規則存進 repository 的 .swiftformat。

# 已安裝 Homebrew 時
brew install swiftformat
swiftformat --version
# 檢查格式，不改檔案
swiftformat --lint .
# 套用格式後查看差異
swiftformat .
git diff

最小 .swiftformat 範例（依專案調整排除路徑）：

--indent 4
--exclude .build,Pods,Carthage
  1. 閱讀格式化差異

    SwiftFormat 可調整語法形式，修改後仍需建置與測試；大批格式化可獨立成一個 commit，方便功能 Review。

  2. 統一版本與設定

    記錄使用的 SwiftFormat 版本，讓同學與 CI 使用相同版本和規則。將 .swiftformat 一起提交；語言版本選項應符合專案設定。

  3. 分清楚 format 與 lint

    一般執行會修改檔案；--lint 只檢查，發現格式問題會回傳失敗狀態。CI 先用 lint，把修正留在本機提交。

06 ／ GitHub Actions

PR 更新時，自動執行檢查

在學生 App repository 新增 .github/workflows/swift-checks.yml。以下是格式檢查起步範例，使用 macOS runner 的 SwiftFormat；主分支名稱與工具版本要配合專案。

name: Swift checks

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

permissions:
  contents: read

jobs:
  format:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v7
      - name: Check SwiftFormat version
        run: swiftformat --version
      - name: Check formatting
        run: swiftformat --lint . --reporter github-actions-log
on
指定 PR 或主分支 Push 何時觸發工作。
jobs／runs-on
每個 job 在 runner 執行。iOS 的 Xcode 建置與 Simulator 測試需要 macOS 與相符工具鏈。
steps
先 checkout 原始碼，再執行版本與格式檢查。
permissions
這份範例只需讀取 repository，設定 contents: read。
  1. 先完成格式檢查

    Commit、Push workflow 與 .swiftformat，在 PR 的 Checks 或 repository 的 Actions 看執行結果。確認 log 中有實際執行 swiftformat。

  2. 練習失敗到修正

    在練習分支製造一個格式差異，確認檢查失敗；本機格式化、審查、Commit、Push，再確認新一輪成功。

  3. 再加建置與聚焦測試

    請 Agent 先列出 workspace／project、共享 scheme、runner 可用的 Xcode 與 Simulator。把本機已成功的 build／test 指令調整成 CI steps，再執行驗證。

# 在 runner 上先確認可用環境與目的地
xcodebuild -version
xcrun simctl list devices available
xcodebuild -list -workspace YourApp.xcworkspace
xcodebuild -showdestinations -workspace YourApp.xcworkspace -scheme YourScheme
# 將路徑、scheme 與 UDID 換成實際值，才加入 workflow
xcodebuild -workspace YourApp.xcworkspace -scheme YourScheme -destination "platform=iOS Simulator,id=YOUR_SIMULATOR_UDID" build
xcodebuild -workspace YourApp.xcworkspace -scheme YourScheme -destination "platform=iOS Simulator,id=YOUR_SIMULATOR_UDID" test

純 project 使用 -project YourApp.xcodeproj。記錄並固定合適的 Xcode、runner 與 SwiftFormat 版本；保留 Xcode 預設 DerivedData。格式 job 綠燈只代表格式通過，建置與測試需各自確認；iPhone 實際操作證據仍要提供。

07 ／ 本週交付

交出一個有審查與檢查紀錄的 PR

08 ／ 官方參考

Git、GitHub 與工具文件

← 返回第 7 週課綱