# PaddleOCR Release SOP

[English](./RELEASING.md)

## 适用范围

本文档用于说明 PaddleOCR 的标准发版流程。

## 版本类型

当前流程支持以下两类发布：

- `bump patch`：例如 `3.4.0 -> 3.4.1`
- `bump minor`：例如 `3.4.x -> 3.5.0`

对于 `bump major`：

- 当前流程暂不支持直接覆盖这类场景
- 如需发布大版本，需要单独讨论并设计额外流程，例如引入额外分支或新的版本准备方式

## 发版原则

- 日常开发在 `main` 分支进行
- 正式发布只在 `release/X.Y` 分支进行
- 正式标签只使用 `vX.Y.Z`
- 不在 `main` 分支打正式发布标签

## 标准发版流程

### 1. 确认发布目标

先确认本次发布属于哪一条版本线，以及目标版本号。

示例：

- 发布 `3.4.1`，对应分支为 `release/3.4`
- 发布 `3.5.0`，对应分支为 `release/3.5`

### 2. 创建或切换到 release 分支

如果该版本线尚未建立，则从 `main` 创建对应的 `release/X.Y` 分支。  
如果该版本线已存在，则直接切换到该分支继续发版准备。

要求：

- 一个 minor 版本线对应一个固定的 `release/X.Y` 分支
- 该分支只承载该版本线的发布内容和补丁修复

### 3. 从 main 挑选发布内容

根据本次发布范围，从 `main` 将需要发布的提交按需 `cherry-pick` 到 `release/X.Y`，直到版本内容 ready。

要求：

- 只挑选本次发布需要的内容
- 避免把与本次发布无关的新功能带入 release 分支
- 如果 release 分支上出现专门的发布修复，也应仅限于本次发布范围

### 4. 完成发布前检查

在 `release/X.Y` 上完成发布前检查。

至少应包括：

- 当前分支正确
- 工作区干净
- 版本号符合预期
- 关键功能验证通过
- 必要的测试、构建、打包和回归通过
- 发布说明已经准备好

### 5. 打正式标签

确认版本 ready 后，在 `release/X.Y` 分支上打正式标签：

- 标签格式必须为 `vX.Y.Z`

示例：

- `v3.4.1`
- `v3.5.0`

要求：

- 标签必须打在本次正式发布对应的 release 分支上
- 不使用开发态标签作为正式发布标签

### 6. 发布 GitHub Release

在 GitHub 上基于本次正式标签创建 Release。

### 7. 更新依赖约束与发布说明

如果本次发布是新的 minor 版本首发，或本次发布涉及 PaddleX 依赖变化，则在正式标签发布前后同步完成相关更新。

至少应包括：

- 检查 `pyproject.toml` 中 `paddlex` 相关依赖约束是否与本次发布版本匹配
- 检查安装说明、升级说明和发布说明中的版本信息是否与本次发布一致

完成要求：

- `paddlex` 相关依赖约束与本次发布目标一致
- 文档中的版本信息与本次发布版本一致

### 8. 将 release 分支的 lineage 同步回 main

当一条新的 `release/X.Y` 发布线完成首个正式版本发布后，需要将该 `release/X.Y` 的 lineage 同步回 `main`。

这一步是当前流程中的固定步骤，每条新的 minor 发布线至少执行一次。

目的：

- 让 `main` 正确感知该发布线已经完成的正式版本
- 保持后续开发与发布节奏一致

要求：

- 每条新的 `release/X.Y` 在首个正式版本发布后执行一次
- 同一条 `release/X.Y` 后续如果继续发布补丁版本，通常不要求重复执行

### 9. 进入下一轮开发或补丁发布

发布完成后：

- `main` 继续进行后续开发
- `release/X.Y` 继续维护该版本线

如果后续还要发布该版本线的补丁版本：

- 继续在 `release/X.Y` 上准备补丁
- 从 `main` 按需 `cherry-pick`
- 重复执行本 SOP 中的发布步骤

## 不同 bump 类型的处理方式

### Patch 发布

适用场景：

- 修复线上问题
- 小范围兼容性修复
- 文档、依赖或稳定性补丁

处理方式：

- 在现有 `release/X.Y` 分支上继续准备内容
- 打下一个 patch 标签，例如 `v3.4.2`

### Minor 发布

适用场景：

- 开启一条新的发布线
- 发布下一阶段稳定版本，例如 `3.5.0`

处理方式：

- 从 `main` 建立新的 `release/X.Y`
- 按标准流程准备版本内容
- 打首个正式标签，例如 `v3.5.0`
- 如有需要，同步更新 `paddlex` 相关依赖约束
- 发布后将该 release 分支的 lineage 同步回 `main`

### Major 发布

当前结论：

- 暂不纳入本 SOP
- 后续需要单独讨论并设计流程

在新的方案明确之前，不建议直接套用当前 minor/patch 的做法处理 major 发布。

## 发布检查清单

每次发版前，请确认以下事项：

- 已确认目标版本号和对应 release 分支
- release 分支中的内容已经 ready
- 发布范围已经收敛
- 关键测试和回归已通过
- 发布说明已准备完成
- 正式标签格式为 `vX.Y.Z`
- GitHub Release 已创建
- 如本次是该 `release/X.Y` 的首个正式版本，发布完成后已将 lineage 同步回 `main`

## 日常维护建议

- 新功能优先进入 `main`
- 正式发布始终通过 `release/X.Y` 执行
- 补丁版本始终在对应的 `release/X.Y` 上维护
- 每条新的 `release/X.Y` 在首个正式版本发布后执行一次 lineage 同步

如当前流程发生调整，应同步更新本文档。