---
source: ../../../core/change-batching-standards.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-03-18
status: current
---

# 變更批次標準

> **語言**: [English](../../../core/change-batching-standards.md) | 繁體中文

**適用範圍**: 所有使用自動化開發流程的軟體專案
**Scope**: universal

---

## 概述

變更批次標準定義了待處理變更應如何累積、評估並合併為原子性提交。本標準填補了個別變更與提交之間的空白，提供在何時以及如何將多個相關變更批次整合為有機一體的規則。

## 參考資料

| 標準／來源 | 內容 |
|------------|------|
| SWEBOK v4.0 第 6 章 | 軟體配置管理 |
| ISO/IEC 12207 | 配置管理流程 |
| Continuous Delivery（Jez Humble） | 小批次原則 |
| Lean Software Development | 批次大小最佳化 |

---

## 待處理變更狀態機

### 狀態定義

```
┌─────────┐    threshold met    ┌─────────┐    merge success    ┌─────────┐
│ PENDING │───────────────────▶│  READY  │────────────────────▶│ MERGED  │
│ 等待中   │                    │ 就緒     │                     │ 已合併   │
└─────────┘                    └─────────┘                     └─────────┘
     ▲                              │                               │
     │ reset                        │ merge failure                 │
     │                              ▼                               ▼
     │                        ┌─────────┐                    ┌──────────┐
     └────────────────────────│ FAILED  │                    │ ARCHIVED │
                              │ 失敗     │                    │ 已歸檔    │
                              └─────────┘                    └──────────┘
```

### 狀態轉換

| 來源 | 目標 | 觸發條件 | 動作 |
|------|------|----------|------|
| PENDING | PENDING | 新增變更 | 遞增計數器，重新評估門檻 |
| PENDING | READY | 達到門檻 | 準備合併批次，執行合併前驗證 |
| READY | MERGED | 合併成功 | 建立提交、清除批次、歸檔 |
| READY | FAILED | 合併失敗 | 記錄失敗，保留變更 |
| FAILED | PENDING | 重置 | 重新排入變更，清除失敗狀態 |
| MERGED | ARCHIVED | 提交後 | 記錄批次元資料以供稽核 |

---

## 門檻策略

### 門檻類型

| 策略 | 參數 | 預設值 | 說明 |
|------|------|--------|------|
| **計數** | `maxChanges` | 5 | 累積 N 個個別變更後合併 |
| **分數** | `maxScore` | 10 | 累積變更分數 ≥ M 時合併 |
| **時間** | `maxAge` | 30m | 最舊的待處理變更超過 TTL 時合併 |
| **手動** | — | — | 僅在使用者明確要求時合併 |

### 變更評分

每項變更依複雜度指派分數：

| 變更類型 | 分數 | 範例 |
|----------|------|------|
| 微小 | 1 | 錯字修正、空白、註解更新 |
| 次要 | 2 | 單一函式變更、變數重新命名 |
| 標準 | 3 | 新增函式、修改邏輯流程 |
| 複雜 | 5 | 多檔案變更、API 修改 |
| 關鍵 | 8 | Schema 變更、破壞性變更 |

### 門檻配置

```json
{
  "batching": {
    "strategy": "count",
    "maxChanges": 5,
    "maxScore": 10,
    "maxAge": "30m",
    "fallbackStrategy": "time"
  }
}
```

### 複合門檻

多個門檻可以 OR 邏輯組合（第一個達到的門檻觸發合併）：

```
Merge when: changes ≥ 5 OR score ≥ 10 OR age ≥ 30m
```

---

## 合併規則

### 優先順序

1. **相同規格親和性**：參照相同 SPEC-ID 的變更優先合併
2. **相同檔案分組**：對相同檔案的變更合併在一起
3. **依賴順序**：有依賴關係的變更依依賴順序合併
4. **時間順序**：在相同優先級內，依建立順序合併

### 衝突解決

| 衝突類型 | 解決策略 | 備用方案 |
|----------|----------|----------|
| 同一檔案同一行 | 最新變更優先 | 手動解決 |
| 重疊函式 | 盡可能進行語義合併 | 手動解決 |
| 依賴衝突 | 先解決依賴關係 | 拒絕批次，拆分 |

### 合併前驗證

合併批次前，需驗證：

| 檢查項目 | 必要性 | 說明 |
|----------|--------|------|
| 所有測試通過 | 是 | 對合併後狀態執行測試套件 |
| 無 lint 錯誤 | 是 | 對合併後的檔案執行 linter |
| 無衝突 | 是 | 確認乾淨合併，無衝突 |
| 維持 AC 覆蓋率 | 建議 | AC 覆蓋率不降低 |

---

## 原子性保證

### 全有或全無原則

批次合併必須是原子性的：

- **成功**：批次中的所有變更一起提交
- **失敗**：批次中的任何變更都不提交；所有變更回到 PENDING 狀態

### 原子性規則

| 規則 | 說明 |
|------|------|
| **單一提交** | 每個合併批次恰好產生一個提交 |
| **不允許部分合併** | 如果批次中任一變更驗證失敗，整個批次被拒絕 |
| **支援回溯** | 失敗的合併必須將所有變更還原至 PENDING 狀態 |
| **隔離性** | 批次合併不得影響批次以外的變更 |

---

## 回溯機制

### 失敗處理

當批次合併失敗時：

1. **記錄失敗**：記錄批次中包含哪些變更以及什麼失敗
2. **保留變更**：所有變更回到 PENDING 狀態
3. **診斷**：識別失敗的變更
4. **選項**：
   - 修正失敗的變更並重試
   - 移除失敗的變更並合併其餘部分
   - 將批次拆分為較小的群組

### 回溯觸發條件

| 觸發條件 | 動作 | 自動執行？ |
|----------|------|-----------|
| 測試失敗 | 拒絕整個批次 | 是 |
| lint 錯誤 | 拒絕整個批次 | 是 |
| 合併衝突 | 拒絕並通知 | 是 |
| 建置失敗 | 拒絕整個批次 | 是 |
| 手動拒絕 | 回到 PENDING | 否 |

---

## 批次提交訊息格式

批次提交應使用結構化訊息格式：

```
<type>(<scope>): <summary of batch>

Changes included:
- <change 1 description>
- <change 2 description>
- <change 3 description>

Spec: SPEC-XXX (if applicable)
Batch: N changes, score M
```

### 範例

```
feat(auth): implement login validation and error handling

Changes included:
- Add email format validation
- Add password strength check
- Add error message display
- Add rate limiting for failed attempts

Spec: SPEC-001
Batch: 4 changes, score 11
```

---

## 反模式

| 反模式 | 影響 | 正確做法 |
|--------|------|----------|
| 無限累積 | 龐大且難以審查的提交 | 設定合理門檻 |
| 混合不相關的變更 | 難以審查，難以回溯 | 依規格或功能分組 |
| 部分提交 | 損壞的中間狀態 | 強制原子性 |
| 忽略失敗 | 損壞的程式碼進入程式庫 | 合併前始終進行驗證 |
| 無回溯計畫 | 失敗時遺失變更 | 失敗時保留變更 |

---

## 最佳實踐

### 應該做的

- ✅ 為自動批次設定明確的門檻
- ✅ 依規格或功能分組變更
- ✅ 提交前驗證整個批次
- ✅ 使用原子性提交（全有或全無）
- ✅ 失敗時保留變更
- ✅ 記錄批次決策以供稽核

### 不應該做的

- ❌ 無限期累積變更
- ❌ 在一個批次中混合不相關的變更
- ❌ 提交部分批次
- ❌ 忽略驗證失敗
- ❌ 合併失敗時遺失變更

---

## 相關標準

- [簽入標準](checkin-standards.md) — 提交的品質閘門
- [Pipeline 整合標準](pipeline-integration-standards.md) — Pipeline 自動化
- [提交訊息指南](commit-message-guide.md) — 提交訊息格式

---

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 1.0.0 | 2026-03-18 | 初始版本 — 狀態機、門檻策略、原子性保證 |
