結業專題

1兩條路線 Two tracks

知識線找不到審查者、只能一個人做？見第 5 節「單人變通版」。軟件線必須是三人小組。

2建議節奏 Suggested pacing

以下是三週的建議分配，小組和自學者都適用。不設硬性日期，按自己的進度調整；重點是先把閘門裝好，再開始做內容。

3軟件線檢核清單 Software track

每一項下面的灰字是「證據放在哪裏」。評核者看不到你的勾選，只看倉庫裏的證據；做完一項，就把證據寫進 README 的「過程記錄」（範本見第 7 節）。

4知識線檢核清單 Knowledge track

同樣，灰字是證據的位置。

5單人變通版 Solo variant

知識線的自學者如果真的找不到任何審查者，可以用這個變通版：自己分飾「作者」和「協作者」兩個角色。先搞清楚 GitHub 容許甚麼：

• 作者不能批准自己的 PR。在自己的 PR 上，Approve 和 Request changes 都不能用，只能提交 Comment 類的審查。
• 不要為此開第二個 GitHub 帳號。GitHub 服務條款規定每人最多一個免費個人帳號；另外可以有一個機器帳號（machine account），但只限用來跑自動化，不能拿來手動批准自己的 PR。
• 不能 fork 自己的倉庫到同一個帳號。所以「外部貢獻」要改用第二個 clone 開分支模擬。

因此單人版的分工是：git 身份（commit 上的作者名）可以有兩個，GitHub 帳號只有一個。做法：

# 1. 主 clone：你自己（作者身份）
git clone https://github.com/你的帳號/notes.git notes
# 2. 第二個 clone：扮演協作者，只在這個倉庫設定另一個 git 身份
git clone https://github.com/你的帳號/notes.git notes-collab
cd notes-collab
git config user.name  "協作者（單人模擬）"
git config user.email "collab@example.com"   # 任何不屬於你帳號的電郵都可以
# 3. 協作者在自己的分支改動，推上去，開 PR
git switch -c collab/補充第三章
#    …改動、commit…
git push -u origin collab/補充第三章
gh pr create --fill
# 4. 回到作者身份審查這個 PR：只能留 Comment 類審查
gh pr review 7 --comment --body "第 12 行的出處請補上頁碼"

單人版的檢核清單照第 4 節做，以下幾項改變：

評核時，單人版的「PR 與審查」一項看 Comment 審查的質素；README 要寫明採用單人變通版。單人版沒有真正的他人審查，總等級最高為 B。

6證據：評核者看甚麼 Evidence

評核者只看倉庫，不看你的電腦。有些事倉庫本身就記錄了（commit、PR、審查、標籤）；有些只發生在你的終端機裏（bisect、worktree、log -S），必須把原始輸出貼進 README 的「過程記錄」一節，或放進 evidence/ 資料夾再從 README 連過去。

保護規則的設定，有讀取權的人看不全，所以要你提供：

• 用 ruleset（建議）：任何能讀倉庫的人都可以用 gh api repos/帳號/倉庫/rules/branches/main 看到 main 上生效的規則，但看不到繞過名單；繞過名單只回傳給有寫入權的人。所以請你自己執行下面兩句，把第二句的輸出存成 evidence/protection.json：

  gh api repos/帳號/倉庫/rulesets --jq '.[] | "\(.id) \(.name) \(.enforcement)"'
  gh api repos/帳號/倉庫/rulesets/編號 > evidence/protection.json   # 含 bypass_actors

• 用舊式的分支保護（classic branch protection）：只有管理員讀得到。執行 gh api repos/帳號/倉庫/branches/main/protection > evidence/protection.json，或者在 Settings 頁截圖。

軟件線另外看個人貢獻。評核者會執行這幾句，你也可以先自己跑一次，確認每人都有份：

git shortlog -sn main          # 每人在 main 上的 commit 數（squash 合併時改看下一句）
gh pr list --state merged --limit 100 --json number,author,reviews \
  --jq '.[] | "#\(.number)\t\(.author.login)\t審查：\([.reviews[].author.login] | unique | join(", "))"'

第二句逐個 PR 列出作者和審查者。每位組員都要有自己開的 PR，也要在別人的 PR 上出現為審查者。README 列出組員與 GitHub 帳號的對照（只寫帳號名，不寫學號、電話等個人資料）。

7範本 Templates

以下三份可以直接複製進倉庫再修改。

PR 範本：.github/pull_request_template.md

放在這個路徑，開 PR 時 GitHub 會自動填入說明欄。

## 改了甚麼
（一兩句。關聯的 issue：Closes #）

## 為甚麼

## 怎樣驗證
- [ ] 本機跑過測試／預覽過
- [ ] CI 通過

## AI 使用
（沒有使用，或寫明哪些部分由哪個工具產生；commit 已加 Co-authored-by trailer）

README 的「過程記錄」與「反思」

## 組員（軟件線）／ 協作方式（知識線）
- 組員 A：@帳號　組員 B：@帳號　組員 C：@帳號
-（單人變通版：寫明採用單人變通版，協作者身份的 git 名稱是 ____）

## 過程記錄
### 保護規則
設定方式：ruleset／classic；輸出見 evidence/protection.json

### CI
被 CI 擋下的 PR：#__，原因：____

### 合併衝突
PR #__：衝突在 ____，在分支上用 merge／rebase 解決，選擇的版本是 ____

### rebase -i（軟件線）
PR #__：整理前
（貼 git log --oneline）
整理後
（貼 git log --oneline）

### worktree（軟件線）／兩個 clone 的分歧（知識線）
（貼 git worktree list 輸出）／（貼 push 被拒的訊息，和解決分歧的 commit）

### bisect（軟件線）／log -S（知識線）
（貼 git bisect log 輸出，或 log -S 的命令與輸出）
找到的 commit：____（來自 PR #__）

### hook（軟件線）
腳本：hooks/pre-commit；啟用：git config core.hooksPath hooks
被擋下時的訊息：（貼上）

## 反思
- 一次出錯：發生了甚麼，怎樣發現
- 怎樣救回來：用了哪個命令（reflog／revert／restore／bisect…），為甚麼選它
- 下次怎樣避免
- AI 使用：哪些改動由 AI 產生，你怎樣檢查它（或寫「沒有使用 AI」）

知識線的連結檢查 CI：.github/workflows/links.yml

檢查兩種內部連結：Obsidian 的 [[筆記名]]，以及 Markdown 的 [文字](相對路徑.md)。找到斷鏈就列出並失敗。設定保護規則時，把 links 這個檢查設為「必須通過」。

name: links
on:
  pull_request:
  push:
    branches: [main]
jobs:
  links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 檢查內部連結
        shell: python
        run: |
          import pathlib, re, sys
          from urllib.parse import unquote
          notes = {p.stem for p in pathlib.Path('.').rglob('*.md')}
          bad = []
          for p in pathlib.Path('.').rglob('*.md'):
              text = p.read_text(encoding='utf-8')
              for name in re.findall(r'\[\[([^\]|#]+)', text):
                  if name.strip().split('/')[-1] not in notes:
                      bad.append(f'{p}: [[{name}]]')
              for target in re.findall(r'\]\(([^)#\s]+\.md)\)', text):
                  if not (p.parent / unquote(target)).exists():
                      bad.append(f'{p}: ({target})')
          print('\n'.join(bad) or '沒有斷鏈')
          sys.exit(1 if bad else 0)

它只認筆記檔名（不分資料夾），也不檢查外部網址和圖片；夠用就好，需要時再擴充。軟件線的 CI 則跑你自己的測試，格式參考 M11 CI 一節。

8使用 AI 的規定 Using AI

可以讓 AI agent 參與，但照 M13 的做法（一個 agent 一張書桌、追溯）：

• 每個 agent 一個 worktree、一條分支，經 PR 合併。
• 含 AI 產生內容的 commit，在說明最後一段加 trailer，一行一個工具：Co-authored-by: 工具名 <電郵>。例如：

  補充第三章的例子
  
  Co-authored-by: Claude <noreply@anthropic.com>

  評核者會用 git log -i --grep "^Co-authored-by:" 或 git log --format='%h %(trailers:key=Co-authored-by,valueonly)' 列出這些 commit。PR 範本的「AI 使用」一欄也要填。
• 審查者必須是人。AI 留下的審查意見可以參考，但不算作審查。

沒有照做的後果：漏標，「過程記錄與反思」一項最高只能得 D；評核者可以要求你解釋任何一個 commit 的內容，解釋不了自己提交的改動，整份專題不合格。

9提交 Submission

專題經課程平台提交，不另交報告。提交時準備好以下內容：

1. 倉庫網址。公開倉庫最簡單；私有倉庫要把評核者的 GitHub 帳號加為協作者（帳號在提交入口公布）。倉庫裏不可以有密鑰。
2. release 頁網址，例如 …/releases/tag/v1.0。
3. README：組員對照、「過程記錄」和「反思」兩節（範本見第 7 節）。
4. evidence/protection.json 或保護規則的截圖（見第 6 節）。
5. 路線：軟件線、知識線，或知識線單人變通版。

10評分 Grading rubric

採用等級制。六個準則各評 A、B、C、D 或不合格，按權重合成總等級。

• A、B、C、D 都是合格；D 是合格線，表示剛好達到最低要求。
• 任何一個準則低於 D，或出現下面任何一種不合格情況，總評就是「不合格（需重交）」，不論其他準則多好。
• 總等級：把 A＝4、B＝3、C＝2、D＝1 按權重平均；≥ 3.5 為 A，≥ 2.5 為 B，≥ 1.5 為 C，其餘為 D。單人變通版的總等級最高為 B（見第 5 節）。

「工具運用」的項目：軟件線是合併衝突、rebase -i、worktree、bisect、hook；知識線是大型檔案處理、兩個 clone 的分歧、log -S、救回刪錯的筆記。缺三項或以上，該準則不合格。

不合格情況（需重交）

• main 沒有受保護，或 main 上有未經 PR 的改動（第一個 commit 除外）。
• 沒有任何經審查的 PR（單人變通版：沒有 Comment 審查）。
• 倉庫歷史裏有密鑰或密碼。即使之後刪除，它仍在歷史裏；要先撤銷該密鑰，再清理歷史後重交。
• 沒有 v1.0（或知識線的階段）標籤和 release。
• README 沒有「過程記錄」，評核者無法核實清單項目。
• 未達最低規模（第 1 節）。
• 無法解釋自己提交的改動（見第 8 節）。

個人貢獻（軟件線）

組員的個人等級原則上等於小組等級，但：

• 任何一位組員沒有自己的 commit、沒有自己開的 PR，或沒有審查過別人的 PR，該組員個人不合格，需要補做；不影響其他組員。
• 貢獻明顯少於組員（例如 commit 和 PR 數只有其他人的一小部分），評核者可以把該組員下調一級，並寫明理由。

證據就是第 6 節的 git shortlog -sn 和 PR 列表。分工時就讓每人負責自己的 issue，不要由一個人代為提交。

完成之後 What next

• 回到術語表，看看還有哪個詞說不出它的意思。
• 到 Learn Git Branching 做進階關卡，鞏固 rebase 和遠端操作。
• 把這門課沒講的留待需要時再學：submodule、sparse checkout、Git LFS 的伺服器設定、Git 內部的 packfile。