VERSION_RULES

# 版本发布规则

> **本文档是版本管理的唯一规则来源**

---

## 一、发布机制

### 自动发布

```
git commit → PENDING_CHANGES 累积
                ↓
        每小时定时任务检查
                ↓
    今天未发布 + 有内容 → 自动发布
```

- **触发时机**：每小时定时任务检查
- **发布条件**：今天未发布 + PENDING_CHANGES 有内容
- **一天一版本**：同一天多次提交合并为一个版本

### 手动发布

紧急情况下可手动触发：

```bash
pnpm release           # 自动发布 (patch)
pnpm release --minor   # 手动跳 minor
pnpm release --major   # 手动跳 major
```

---

## 二、版本号规则

### 格式

```
v主版本.次版本.修订版本
示例：v1.2.5
```

### 递增规则

| 类型 | 递增方式 | 触发条件 |
|-----|---------|---------|
| **PATCH** | v1.2.5 → v1.2.6 | 默认自动递增 |
| **PATCH→MINOR** | v1.2.99 → v1.3.0 | patch 达到 99 时自动进位 |
| **MINOR** | v1.2.5 → v1.3.0 | 手动 `--minor` |
| **MAJOR** | v1.2.5 → v2.0.0 | 手动 `--major` |

### 跳版本场景

| 命令 | 适用场景 |
|-----|---------|
| `--minor` | 新增重要功能模块、重要功能更新 |
| `--major` | 架构重构、破坏性变更、不兼容升级 |

---

## 三、更新内容分类

| 分类 | 前缀 | 提交类型 |
|-----|------|---------|
| 新增功能 | `新增：` | feat |
| 问题修复 | `修复：` | fix |
| 体验优化 | `优化：` | chore, docs |
| 代码重构 | `重构：` | refactor |

---

## 四、数据结构

### version.ts 核心字段

```typescript
// 当前版本
export const SYSTEM_VERSION = "v1.2.5";

// 上次发布日期
export const LAST_RELEASE_DATE: string = "2026-03-10";

// 待发布内容（累积区）
export const PENDING_CHANGES: PendingChange[] = [];

// 版本历史
export const VERSION_HISTORY: VersionRecord[] = [...];
```

### 数据流

```
version.ts (唯一数据源)
      ↓
generate-changelog.ts
      ↓
CHANGELOG.md (自动生成)
```

---

## 五、相关命令

```bash
# 手动发布
pnpm release
pnpm release --minor
pnpm release --major

# 生成 CHANGELOG
pnpm changelog:generate

# 查看定时任务日志
tail -f /app/work/logs/bypass/version-release.log
```