Git 簽到系統

這是六角學院 Vibe Coding Camp 的 Git 練習專案，透過 Fork、新增檔案、發 Pull Request 的流程，幫助你熟悉 Git 與 GitHub 的協作方式。

這個專案做什麼？

這是一個自動化的簽到系統，當你提交 Pull Request 時，系統會自動檢查：

自動檢核項目

• ✅ 資料夾命名格式（YYYY-MM-DD-羅馬拼音）
• ✅ 日期格式正確性（年月日是否合理）
• ✅ 羅馬拼音格式（僅允許小寫英數字及連字號）
• ✅ 必要檔案 index.html 存在
• ✅ 檔案數量限制（最多 1 個 PNG、1 個 CSS）
• ✅ 檔案大小限制（每個檔案 ≤ 100 KB）
• ✅ 路徑層級正確（不允許子資料夾）
• ✅ 操作類型（僅允許新增，不可修改/刪除既有檔案）

如何完成簽到？

步驟 1：Fork 本專案

點擊右上角的 Fork 按鈕，將專案 Fork 到你的帳號下（請以公開方式 Fork）。

步驟 2：建立你的簽到資料夾

在 students/ 目錄下新增你的個人資料夾，命名規則：

YYYY-MM-DD-羅馬拼音

範例：

• ✅ 2025-10-03-liaoweichieh
• ✅ 2025-10-28-israynotarray
• ✅ 2025-11-15-chen-hsiao-ming（可使用連字號）
• ❌ 2025-10-03-LiaoWeiChieh（不可使用大寫）
• ❌ 2025-10-03-廖偉傑（不可使用中文）
• ❌ 2025-13-45-test（日期格式錯誤）

步驟 3：新增簽到檔案

在你的資料夾內新增以下檔案：

必要檔案

• index.html：你的個人介紹頁面

可選檔案（非必要，可以不提供）

• people.png：你的照片或頭像（可選，如提供則最多 1 張，≤ 100 KB）
• style.css：自訂樣式（可選，如提供則最多 1 個，≤ 100 KB）

檔案結構範例：

students/
└── 2025-10-03-liaoweichieh/
    ├── index.html    （必要）
    ├── people.png    （可選）
    └── style.css     （可選）

步驟 4：提交 Pull Request

1. 將變更 commit 並 push 到你的 Fork
2. 對本專案的 main 分支發起 Pull Request
3. 等待 GitHub Actions 自動檢核

步驟 5：等待合併

• ✅ 檢核通過後，PR 會自動留言顯示檢核結果
• ✅ 助教審核後會合併你的 PR
• ❌ 如果檢核失敗，請依據錯誤訊息修正後重新 push

簽到規則

檔案規則

項目	規則
資料夾命名	YYYY-MM-DD-羅馬拼音（小寫英數字及連字號）
必要檔案	index.html（必須存在）
可選檔案	0-1 個 .png + 0-1 個 .css（可以都不提供）
檔案大小	每個檔案 ≤ 100 KB
路徑層級	僅允許 students/<folder>/<file>，不可有子資料夾

PR 規則

• ✅ 一次 PR 只能新增一個簽到資料夾
• ✅ 只允許新增檔案，不可修改、刪除、改名既有檔案
• ✅ 只能變更 students/ 目錄下的內容
• ✅ 必須對 main 分支發 PR

GitHub Actions 自動檢核

PR 檢核流程 (pr-check.yml)

何時觸發：當你建立或更新 Pull Request 時

檢核內容：

1. 資料夾命名檢查

   • 驗證 YYYY-MM-DD 日期格式
   • 驗證羅馬拼音格式（僅小寫英數字及連字號）

2. 檔案規則檢查

   • 確認必須有 index.html（必要）
   • 確認 PNG 數量 ≤ 1（可選，0 或 1 個）
   • 確認 CSS 數量 ≤ 1（可選，0 或 1 個）
   • 拒絕其他類型的檔案

3. 檔案大小檢查

   • 透過 GitHub API 取得實際檔案大小
   • 確認每個檔案 ≤ 100 KB

4. 路徑與操作檢查

   • 確認只變更 students/ 目錄
   • 確認路徑層級為 students/<folder>/<file>
   • 確認只有「新增」操作（不允許修改/刪除）

5. 自動留言

   • 檢核通過後，會在 PR 自動留言顯示詳細結果

範例留言：

## ✅ 簽到檢核通過！

### 📋 檢核結果

| 項目 | 結果 |
|------|------|
| 資料夾名稱 | `2025-10-03-liaoweichieh` |
| 日期格式 | 2025-10-03 ✅ |
| 羅馬拼音 | liaoweichieh ✅ |
| 檔案數量 | 3 個 |
| index.html | ✅ 存在 |
| PNG 圖片 | 1 個 ✅ |
| CSS 檔案 | 1 個 ✅ |
| 檔案大小 | 全部 ≤ 100 KB ✅ |

技術細節

使用的技術

• Node.js 20+：使用原生 fetch API，無需外部相依套件
• GitHub Actions：自動化 CI/CD 流程
• GitHub API：取得 PR 檔案資訊、檔案大小、留言等

檢核標準

本專案採用通過/失敗制，而非評分制：

• ✅ 必要條件：

  • 必須有 index.html
  • 資料夾命名正確（YYYY-MM-DD-羅馬拼音）
  • 路徑層級正確（students/<folder>/<file>）
  • 只有新增操作（不可修改/刪除）
  • 所有檔案 ≤ 100 KB

• ✅ 可選條件（有的話需符合）：

  • PNG 圖片：0 個或 1 個（超過 1 個會失敗）
  • CSS 檔案：0 個或 1 個（超過 1 個會失敗）

結果：

• ✅ 所有必要條件 + 可選條件（如果有）都通過 → CI 成功，可合併
• ❌ 任一條件失敗 → CI 失敗，阻擋合併

常見問題 FAQ

Q: 為什麼我的 PR 檢核失敗？

• 檢查資料夾命名是否符合 YYYY-MM-DD-羅馬拼音 格式
• 確認日期格式正確（月份 1-12，日期 1-31）
• 確認羅馬拼音只包含小寫英數字及連字號
• 確認有 index.html 檔案
• 確認 PNG 和 CSS 檔案數量不超過 1 個
• 確認所有檔案 ≤ 100 KB

Q: 我可以使用 JPG 圖片嗎？

• ❌ 不行，只允許 .png 格式
• 如果你的圖片是 JPG，請先轉換為 PNG

Q: 我可以使用 SCSS 或其他 CSS 預處理器嗎？

• ❌ 不行，只允許純 .css 檔案
• 如果你使用 SCSS，請先編譯為 CSS

Q: 我可以新增多個 HTML 檔案嗎（如 about.html）？

• ❌ 不行，只允許 index.html
• 所有內容請寫在 index.html 中

Q: 我可以建立子資料夾來組織檔案嗎？

• ❌ 不行，只允許 students/<folder>/<file> 一層
• 所有檔案必須直接放在你的簽到資料夾下

Q: 我可以在一個 PR 中新增多個日期的簽到嗎？

• ❌ 不行，一次 PR 只能新增一個簽到資料夾
• 如果要補簽，請分多次 PR

Q: 我可以修改之前的簽到內容嗎？

• ❌ 不行，不允許修改既有檔案
• 系統會拒絕任何非「新增」的操作

Q: 檔案大小如何確認？

• 在 macOS Finder 或 Windows 檔案總管中查看檔案大小
• 確保每個檔案 ≤ 100 KB（102,400 bytes）
• 圖片可使用線上壓縮工具（如 TinyPNG）來減小檔案大小

Q: PR 通過檢核後多久會被合併？

• 助教會定期審核並合併通過檢核的 PR
• 請耐心等待，無需催促

Q: CI 檢核通過了，但 PR 沒有自動留言？

• 確認 workflow 有設定正確的權限（pull-requests: write）
• 留言失敗不影響檢核結果，只要 CI 通過即可

授權

本專案由六角學院提供，用於 Vibe Coding Camp 教學用途。

---

如有任何問題，歡迎在 Discord 社群中詢問助教或同學！