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

package/bundled/locales/zh-CN/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-CN/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-CN/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-CN/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-CN/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)