---
source: ../../../core/change-batching-standards.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-03-23
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 | 初始版本 — 状态机、门槛策略、原子性保证 |
