universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-TW/options/commit-message/traditional-chinese.md

@@ -0,0 +1,162 @@
+---
+source: ../../../../options/commit-message/traditional-chinese.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# 繁體中文 Commit 訊息
+
+> **語言**: [English](../../../../options/commit-message/traditional-chinese.md) | 繁體中文
+
+**上層標準**: [Commit 訊息指南](../../core/commit-message-guide.md)
+
+---
+
+## 概述
+
+本選項定義以繁體中文撰寫 commit 訊息的標準。適合以中文為主要溝通語言的團隊，讓 commit 歷史更容易閱讀和理解。
+
+## 適用情境
+
+- 台灣或香港的開發團隊
+- 內部專案（非開源）
+- 中文為主要語言的組織
+- 需要非技術人員閱讀 commit 歷史的專案
+
+## 格式
+
+### 基本結構
+
+```
+<類型>(<範圍>): <主題>
+
+<內文>
+
+<頁尾>
+```
+
+### 組成元素
+
+| 元素 | 必填 | 說明 |
+|------|------|------|
+| 類型 | 是 | 變更類別（feat、fix、docs 等）|
+| 範圍 | 否 | 影響的模組或元件 |
+| 主題 | 是 | 簡短描述 |
+| 內文 | 否 | 詳細說明 |
+| 頁尾 | 否 | 參考連結、重大變更 |
+
+## Commit 類型
+
+| 類型 | 中文說明 | 範例 |
+|------|----------|------|
+| `feat` | 新功能 | `feat: 新增使用者驗證功能` |
+| `fix` | 錯誤修復 | `fix: 修正登入逾時問題` |
+| `docs` | 文件更新 | `docs: 更新 API 參考文件` |
+| `style` | 格式調整 | `style: 修正工具模組縮排` |
+| `refactor` | 程式碼重構 | `refactor: 簡化驗證邏輯` |
+| `perf` | 效能優化 | `perf: 優化資料庫查詢` |
+| `test` | 測試相關 | `test: 新增驗證模組單元測試` |
+| `chore` | 維護作業 | `chore: 更新相依套件` |
+
+## 撰寫指南
+
+### 主題行
+
+1. **使用動詞開頭**：「新增功能」而非「功能新增」
+2. **保持簡潔**：50 字元以內
+3. **不加句號**：「新增功能」而非「新增功能。」
+4. **具體明確**：「修正使用者服務空指標問題」而非「修正錯誤」
+
+### 內文
+
+1. **每行 72 字元**：保持終端機可讀性
+2. **說明原因**：解釋為什麼要做這個變更
+3. **使用列表**：多項變更時使用項目符號
+4. **空行分隔**：與主題行以空行分隔
+
+## 範例
+
+### 簡單功能
+
+```
+feat(auth): 新增密碼強度指示器
+
+- 在密碼輸入時顯示強度條
+- 輸入時顯示密碼要求
+- 阻止提交弱密碼
+
+關閉 #234
+```
+
+### 錯誤修復
+
+```
+fix(api): 處理付款閘道的空值回應
+
+付款閘道在服務降級時偶爾會回傳 null 而非錯誤物件，
+這導致結帳流程出現未處理的例外。
+
+新增空值檢查和適當的錯誤處理，優雅地處理此邊緣案例。
+
+修復 #567
+```
+
+### 重大變更
+
+```
+feat(api): 將驗證改為 JWT 權杖
+
+重大變更：移除基於 Session 的驗證。
+所有 API 客戶端必須使用 JWT 權杖進行驗證。
+
+遷移指南：
+1. 從 /auth/token 端點取得 JWT 權杖
+2. 在 Authorization 標頭中包含權杖
+3. 移除 session cookie 處理
+
+關閉 #789
+```
+
+## 反面教材
+
+### 不良範例
+
+```
+# 太籠統
+fix: 修正錯誤
+
+# 沒有說明
+更新使用者服務
+
+# 無意義
+進行中
+雜項變更
+```
+
+### 改善範例
+
+```
+# 具體明確
+fix(auth): 防止檔案上傳期間 session 逾時
+
+# 簡潔並在內文補充細節
+feat(users): 新增個人頭像上傳功能
+
+支援 JPEG、PNG 和 WebP 格式。
+圖片自動調整為 100x100、200x200 和 400x400 像素。
+```
+
+## 相關選項
+
+- [英文](./english.md) - 英文 Commit 訊息
+- [雙語](./bilingual.md) - 中英雙語格式
+
+---
+
+## 授權條款
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權條款。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/git-workflow/gitflow.md

@@ -0,0 +1,147 @@
+---
+source: ../../../../options/git-workflow/gitflow.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# GitFlow 工作流程
+
+> **語言**: [English](../../../../options/git-workflow/gitflow.md) | 繁體中文
+
+**上層標準**: [Git 工作流程](../../core/git-workflow.md)
+
+---
+
+## 概述
+
+GitFlow 是一個嚴謹的分支模型，專為有排程發布週期的專案設計。它定義了功能開發、發布準備和維護的具體分支角色。
+
+## 適用情境
+
+- 有排程發布週期的專案
+- 需要同時維護多個版本的軟體
+- 企業級應用程式
+- 需要嚴格品質控管的團隊
+
+## 分支架構
+
+```
+main ────●────────●────────●──────── (生產版本)
+         │        │        │
+         │   release/1.0   │
+         │   ┌────●────┐   │
+         │   │         │   │
+develop ─●───●─────────●───●──────── (開發主線)
+         │             │
+    feature/a     feature/b
+    ┌────●────┐   ┌────●────┐
+```
+
+## 分支類型
+
+| 分支 | 用途 | 生命週期 |
+|------|------|----------|
+| `main` | 生產版本，每個 commit 都是發布 | 永久 |
+| `develop` | 開發整合分支 | 永久 |
+| `feature/*` | 新功能開發 | 臨時 |
+| `release/*` | 發布準備 | 臨時 |
+| `hotfix/*` | 緊急生產修復 | 臨時 |
+
+## 工作流程
+
+### 功能開發
+
+```bash
+# 從 develop 建立功能分支
+git checkout develop
+git pull origin develop
+git checkout -b feature/shopping-cart
+
+# 開發完成後合併回 develop
+git checkout develop
+git merge --no-ff feature/shopping-cart
+git push origin develop
+git branch -d feature/shopping-cart
+```
+
+### 發布準備
+
+```bash
+# 從 develop 建立發布分支
+git checkout develop
+git checkout -b release/1.2.0
+
+# 進行發布準備（版本號更新、文件等）
+git commit -m "chore: bump version to 1.2.0"
+
+# 發布就緒後，合併到 main 和 develop
+git checkout main
+git merge --no-ff release/1.2.0
+git tag -a v1.2.0 -m "Release 1.2.0"
+
+git checkout develop
+git merge --no-ff release/1.2.0
+
+git branch -d release/1.2.0
+```
+
+### 緊急修復
+
+```bash
+# 從 main 建立 hotfix 分支
+git checkout main
+git checkout -b hotfix/security-fix
+
+# 修復後合併到 main 和 develop
+git checkout main
+git merge --no-ff hotfix/security-fix
+git tag -a v1.2.1 -m "Hotfix 1.2.1"
+
+git checkout develop
+git merge --no-ff hotfix/security-fix
+
+git branch -d hotfix/security-fix
+```
+
+## 版本標籤
+
+```bash
+# 建立標籤
+git tag -a v1.0.0 -m "版本 1.0.0"
+
+# 推送標籤
+git push origin v1.0.0
+git push origin --tags  # 推送所有標籤
+```
+
+## 優點
+
+| 優點 | 說明 |
+|------|------|
+| 清晰的分支角色 | 每種分支有明確用途 |
+| 支援多版本維護 | 可同時維護多個生產版本 |
+| 發布流程可控 | 有專門的發布準備階段 |
+| 適合大型團隊 | 結構化的協作流程 |
+
+## 缺點
+
+| 缺點 | 說明 |
+|------|------|
+| 複雜度較高 | 需要維護多個長期分支 |
+| 分支管理開銷 | 需要頻繁合併 |
+| 不適合持續部署 | 發布週期較長 |
+
+## 相關選項
+
+- [GitHub Flow](./github-flow.md) - 更簡單的持續部署流程
+- [Trunk-Based](./trunk-based.md) - 最簡化的持續整合流程
+
+---
+
+## 授權條款
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權條款。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/git-workflow/github-flow.md

@@ -0,0 +1,124 @@
+---
+source: ../../../../options/git-workflow/github-flow.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# GitHub Flow 工作流程
+
+> **語言**: [English](../../../../options/git-workflow/github-flow.md) | 繁體中文
+
+**上層標準**: [Git 工作流程](../../core/git-workflow.md)
+
+---
+
+## 概述
+
+GitHub Flow 是一個輕量級、以分支為基礎的工作流程，支援定期部署的團隊和專案。它強調簡單性，只使用一個長期分支（main），並搭配短期功能分支。
+
+## 適用情境
+
+- 持續部署環境
+- 小型到中型團隊
+- Web 應用程式和 SaaS 產品
+- 需要頻繁發布的專案
+
+## 核心原則
+
+| 原則 | 說明 |
+|------|------|
+| Main 隨時可部署 | `main` 分支永遠處於可發布狀態 |
+| 功能分支 | 所有工作在功能分支上進行 |
+| Pull Request | 透過 PR 進行程式碼審查 |
+| 合併後立即部署 | 合併到 main 即觸發部署 |
+
+## 工作流程步驟
+
+### 1. 從 main 建立分支
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/user-authentication
+```
+
+### 2. 進行變更並提交
+
+```bash
+# 進行變更
+git add .
+git commit -m "feat(auth): add login form component"
+
+# 持續提交
+git commit -m "feat(auth): add form validation"
+git commit -m "test(auth): add login form tests"
+```
+
+### 3. 推送並建立 Pull Request
+
+```bash
+git push origin feature/user-authentication
+# 在 GitHub 上建立 Pull Request
+```
+
+### 4. 討論與審查
+
+- 團隊成員審查程式碼
+- 討論變更
+- 進行必要的修改
+- CI/CD 自動執行測試
+
+### 5. 合併並部署
+
+```bash
+# 審查通過後，透過 GitHub 介面合併
+# 或使用命令列：
+git checkout main
+git merge --no-ff feature/user-authentication
+git push origin main
+
+# 刪除功能分支
+git branch -d feature/user-authentication
+git push origin --delete feature/user-authentication
+```
+
+## 分支命名慣例
+
+| 類型 | 格式 | 範例 |
+|------|------|------|
+| 功能 | `feature/<描述>` | `feature/user-profile` |
+| 錯誤修復 | `fix/<描述>` | `fix/login-redirect` |
+| 熱修復 | `hotfix/<描述>` | `hotfix/security-patch` |
+| 文件 | `docs/<描述>` | `docs/api-reference` |
+
+## 優點
+
+| 優點 | 說明 |
+|------|------|
+| 簡單易學 | 只需記住一個流程 |
+| 快速迭代 | 支援持續部署 |
+| 清晰的審查流程 | PR 確保程式碼品質 |
+| 自動化友善 | 易於整合 CI/CD |
+
+## 缺點
+
+| 缺點 | 說明 |
+|------|------|
+| 無發布分支 | 不適合需要版本控制的專案 |
+| 需要可靠的測試 | main 必須隨時可部署 |
+| 不適合多版本維護 | 難以同時維護多個生產版本 |
+
+## 相關選項
+
+- [GitFlow](./gitflow.md) - 適合有排程發布的專案
+- [Trunk-Based](./trunk-based.md) - 更簡化的持續整合流程
+
+---
+
+## 授權條款
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權條款。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/git-workflow/merge-commit.md

@@ -0,0 +1,124 @@
+---
+source: ../../../../options/git-workflow/merge-commit.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Merge Commit 合併策略
+
+> **語言**: [English](../../../../options/git-workflow/merge-commit.md) | 繁體中文
+
+**上層標準**: [Git 工作流程](../../core/git-workflow.md)
+
+---
+
+## 概述
+
+Merge commit（也稱為「true merge」或「merge with merge commit」）透過建立合併 commit 來保留功能分支的完整歷史。這維護了完整的開發歷史，並顯示分支合併的確切時間點。
+
+## 適用情境
+
+- 重視完整歷史保留的團隊
+- 需要審計軌跡的專案
+- 長期執行的功能分支
+- 個別 commit 有意義訊息時
+- 使用 `git bisect` 除錯時
+
+## 運作方式
+
+```
+合併前：                合併後：
+main:    A---B---C      A---B---C---------M（合併 commit）
+              \                   \       /
+feature:       D---E---F           D---E---F
+```
+
+合併 commit `M` 有兩個父節點：`C`（來自 main）和 `F`（來自 feature）。
+
+## 工作流程
+
+### 標準 Merge Commit
+
+```bash
+# 確保 main 是最新的
+git checkout main
+git pull origin main
+
+# 使用 merge commit 合併功能分支
+git merge feature/user-auth --no-ff
+
+# 這會開啟編輯器撰寫合併訊息
+# 或指定訊息：
+git merge feature/user-auth --no-ff -m "Merge feature/user-auth: Add OAuth support"
+
+# 推送
+git push origin main
+```
+
+### `--no-ff` 旗標
+
+`--no-ff`（no fast-forward）旗標確保永遠建立合併 commit：
+
+```bash
+# 不使用 --no-ff（可能會 fast-forward）
+git merge feature-branch
+# 結果：可能會或不會建立合併 commit
+
+# 使用 --no-ff（永遠建立合併 commit）
+git merge --no-ff feature-branch
+# 結果：永遠建立合併 commit
+```
+
+## 優點
+
+| 優點 | 說明 |
+|------|------|
+| 完整歷史 | 所有 commit 保留可見 |
+| 清楚的合併點 | 容易看出功能整合時間 |
+| 容易歸屬 | 每個 commit 顯示作者 |
+| 有效的 bisect | `git bisect` 有完整細節 |
+| 還原彈性 | 可還原合併或個別 commit |
+
+## 缺點
+
+| 缺點 | 說明 |
+|------|------|
+| 非線性歷史 | 分支結構可能複雜 |
+| 更多 commit | 主分支累積許多 commit |
+| 較難閱讀 | `git log` 顯示交錯 commit |
+| 合併衝突 | 衝突在合併 commit 解決 |
+
+## 檢視合併歷史
+
+```bash
+# 只列出合併 commit
+git log --merges --oneline
+
+# 視覺化分支結構
+git log --oneline --graph
+```
+
+## 還原合併
+
+```bash
+# 還原整個合併
+git revert -m 1 <merge-commit-sha>
+
+# -m 1 表示保留第一個父節點（main 分支）
+# -m 2 會保留第二個父節點（feature 分支）
+```
+
+## 相關選項
+
+- [Squash Merge](./squash-merge.md) - 將所有 commit 合併為一個
+- [Rebase and Fast-Forward](./rebase-ff.md) - 無合併 commit 的線性歷史
+
+---
+
+## 授權條款
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權條款。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-TW/options/git-workflow/rebase-ff.md

@@ -0,0 +1,160 @@
+---
+source: ../../../../options/git-workflow/rebase-ff.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-30
+status: current
+---
+
+# Rebase and Fast-Forward 策略
+
+> **語言**: [English](../../../../options/git-workflow/rebase-ff.md) | 繁體中文
+
+**上層標準**: [Git 工作流程](../../core/git-workflow.md)
+
+---
+
+## 概述
+
+Rebase and fast-forward 是一種合併策略，透過將功能分支的 commit 重新播放到目標分支上方，建立完全線性的歷史。結果是乾淨、直線的歷史，所有 commit 看起來像是在單一分支上依序完成的。
+
+## 適用情境
+
+- 偏好線性歷史的團隊
+- 大量依賴 `git bisect` 的專案
+- 想要乾淨、可讀日誌的開發者
+- 有高程式碼品質標準的開源專案
+
+## 運作方式
+
+```
+rebase 前：              rebase + fast-forward 後：
+main:    A---B---C       A---B---C---D'---E'---F'
+              \                         (rebased commits)
+feature:       D---E---F
+```
+
+Commit D、E、F 被「重新播放」為 D'、E'、F' 在 C 之上。
+
+## 工作流程
+
+### 合併前的互動式 Rebase
+
+```bash
+# 在功能分支上開始
+git checkout feature/user-profile
+
+# 取得最新變更
+git fetch origin
+
+# Rebase 到 main 上
+git rebase origin/main
+
+# 如有衝突，解決後繼續
+git add <resolved-files>
+git rebase --continue
+
+# 或需要時中止
+git rebase --abort
+```
+
+### Fast-Forward 合併
+
+```bash
+# 切換到 main
+git checkout main
+git pull origin main
+
+# Fast-forward 合併（只在 feature 領先時有效）
+git merge --ff-only feature/user-profile
+
+# 推送
+git push origin main
+
+# 清理
+git branch -d feature/user-profile
+```
+
+### Rebase 後的 Force Push
+
+當你 rebase 了已推送的分支：
+
+```bash
+# rebase 後
+git push --force-with-lease origin feature/user-profile
+
+# --force-with-lease 比 --force 安全
+# 如果其他人推送到該分支會失敗
+```
+
+## 互動式 Rebase
+
+合併前清理 commit：
+
+```bash
+# 互動式 rebase 最近 4 個 commit
+git rebase -i HEAD~4
+
+# 或從分支點 rebase
+git rebase -i main
+```
+
+### 常用清理模式
+
+```
+pick abc1234 feat: add user model
+fixup def5678 fix typo in user model
+fixup ghi9012 another fix
+
+# 結果：單一乾淨的 commit
+```
+
+## 優點
+
+| 優點 | 說明 |
+|------|------|
+| 線性歷史 | 容易閱讀和理解 |
+| 乾淨日誌 | `git log` 顯示直線 |
+| 有效的 bisect | 清楚的變更進程 |
+| 原子 commit | 每個 commit 獨立完整 |
+| 無合併 commit | 更乾淨的儲存庫 |
+
+## 缺點
+
+| 缺點 | 說明 |
+|------|------|
+| 重寫歷史 | Commit SHA 在 rebase 後改變 |
+| 需要 force push | rebase 已推送的分支後 |
+| 衝突解決 | 可能需要多次解決衝突 |
+| 失去合併脈絡 | 無分支合併時間記錄 |
+| 共享時危險 | 可能對協作者造成問題 |
+
+## Rebase 的黃金法則
+
+**永遠不要 rebase 已推送到共享分支的 commit。**
+
+```bash
+# 安全：rebase 本地 commit
+git rebase main  # 如果功能分支未推送
+
+# 注意：rebase 已推送的功能分支
+git rebase main
+git push --force-with-lease  # 只有在你是唯一工作者時
+
+# 危險：永遠不要這樣做
+git checkout main
+git rebase feature  # 永遠不要 rebase main/master！
+```
+
+## 相關選項
+
+- [Squash Merge](./squash-merge.md) - 單一 commit，更簡單的工作流程
+- [Merge Commit](./merge-commit.md) - 保留分支歷史
+
+---
+
+## 授權條款
+
+本文件採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權條款。
+
+**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)