PaddleOCR Release SOP 发版流程全解从分支模型到vX.Y.Z标签的九步标准操作【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本篇指南完整解读 PaddleOCR 仓库中维护的官方发版规范RELEASING.md另有中文版系统讲解其main 日常开发 release/X.Y 正式发布的分支模型、patch/minor/major 三种版本类型的处理边界以及从确认目标到标签发布、依赖约束更新、lineage 同步回 main 的完整九步流程。读完本文你将掌握 PaddleOCR 版本线的组织方式、如何正确从 main 挑选内容、如何在 release 分支打正式标签以及发布前后需要核对的全部检查项可直接用于指导实际发版操作。一、文档定位与适用范围RELEASING.mdRelease SOPStandard Operating Procedure是 PaddleOCR 仓库中描述标准发版流程的规范文档与仓库根目录下的 RELEASING_cn.md 为同一份内容的英文/中文双语文档。它面向的是 PaddleOCR 的维护者与发布负责人回答的核心问题是一次官方版本发布应该走什么样的分支、打什么样的标签、做哪些检查、发完以后还要做什么。该文档不涉及具体 OCR 算法的实现而是聚焦于工程发布治理版本类型、分支模型、cherry-pick 内容挑选、发布前检查、正式标签规范、GitHub Release 创建、依赖约束与文档版本对齐以及 release 分支 lineage 向 main 的同步。二、版本类型patch 与 minor 的明确边界SOP 明确当前流程支持两类发布bump版本类型示例语义bump patch3.4.0 - 3.4.1在既有版本线内发布补丁版本bump minor3.4.x - 3.5.0开启一条新的版本线发布下一阶段稳定版本对于bump majorSOP 给出明确结论当前流程暂不支持直接覆盖。如果需要发布大版本必须单独讨论并设计额外流程例如引入额外分支或新的版本准备方式在新方案明确之前不建议直接套用 minor/patch 的做法处理 major 发布。从仓库实际版本历史见 docs/update/update.md可以印证这一模型的运行方式PaddleOCR 3.x 系列以 minor 版本3.0.0、3.1.0、3.2.0开启新版本线再以 patch 版本3.0.1、3.0.2、3.0.3、3.1.1在同一版本线上发布修复与稳定性更新。三、发版原则双分支模型SOP 明确规定的分支与标签纪律是整套流程的基石日常开发在main分支进行——所有新功能、新模型、新产线的开发先合入 main正式发布只在release/X.Y分支进行——每个 minor 版本线对应一条固定的发布分支正式标签只使用vX.Y.Z格式例如v3.4.1、v3.5.0不在main分支打正式发布标签也不使用开发态标签作为正式发布标签。这种模型保证 main 始终处于持续演进状态而 release 分支保持稳定、可追溯任何时刻都能从 release 分支产出可复现的官方版本。四、标准发版流程九步详解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上完成发布前检查至少应包括当前分支正确工作区干净无未提交改动版本号符合预期关键功能验证通过必要的测试、构建、打包和回归通过发布说明已经准备好。对应到本仓库可在 release 分支上确认paddleocr/_version.py读取到的版本信息与目标一致并运行仓库测试目录如 tests/、test_tipc/中的相关测试与回归用例。5. 打正式标签确认版本 ready 后在release/X.Y分支上打正式标签格式必须为vX.Y.Z例如v3.4.1、v3.5.0。要求标签必须打在本次正式发布对应的 release 分支上不使用开发态标签作为正式发布标签。值得补充的是标签格式与版本号解析在仓库构建链中是强耦合的pyproject.toml 中[tool.setuptools_scm]配置了version_scheme release-branch-semver并要求git describe时匹配v[0-9]*前缀的标签。也就是说正式标签命名直接决定了 setuptools_scm 能否从 git 历史推导出正确的发布版本号这也解释了 SOP 为何将vX.Y.Z格式列为硬性要求。6. 发布 GitHub Release在 GitHub 上基于本次正式标签创建 Release发布说明应与此前的发布准备对齐。7. 更新依赖约束与发布说明如果本次发布是新的 minor 版本首发或本次发布涉及 PaddleX 依赖变化则在正式标签发布前后同步完成相关更新至少包括检查pyproject.toml中paddlex相关依赖约束是否与本次发布版本匹配检查安装说明、升级说明和发布说明中的版本信息是否与本次发布一致。完成要求paddlex相关依赖约束与本次发布目标一致文档中的版本信息与本次发布版本一致。这一步在源码中有非常直接的对应物当前 pyproject.toml 的dependencies中声明了paddlex[ocr-core]3.7.0,3.8.0各可选依赖组doc-parser、ie、trans、all同样以上下界约束锁定 paddlex 版本。发版时若目标版本与 paddlex 依赖区间不符必须同步调整该文件。同时需要核对的文档包括 docs/version3.x/installation.md安装说明、docs/update/upgrade_notes.md升级说明以及 docs/update/update.md更新日志。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。SOP 中的 1~4、6、9 步在该场景下按需复用。Minor 发布适用场景开启一条新的发布线发布下一阶段稳定版本例如3.5.0。处理方式对应完整的九步流程从main建立新的release/X.Y按标准流程准备版本内容cherry-pick打首个正式标签例如v3.5.0如有需要同步更新paddlex相关依赖约束第 7 步发布后将该 release 分支的 lineage 同步回main第 8 步。Major 发布当前结论暂不纳入本 SOP后续需要单独讨论并设计流程。在新的方案明确之前不建议直接套用当前 minor/patch 的做法处理 major 发布。这与 2.x - 3.x 的实际演进路径相互印证——3.0 是脱离常规补丁节奏、专门设计的大版本升级背景与动机详见 docs/update/upgrade_notes.md。六、发布检查清单每次发版前SOP 要求确认以下事项已确认目标版本号和对应 release 分支release 分支中的内容已经 ready发布范围已经收敛关键测试和回归已通过发布说明已准备完成正式标签格式为vX.Y.ZGitHub Release 已创建如本次是该release/X.Y的首个正式版本发布完成后已将 lineage 同步回main。七、日常维护建议SOP 给出的日常维护准则可以概括为四条新功能优先进入main正式发布始终通过release/X.Y执行补丁版本始终在对应的release/X.Y上维护每条新的release/X.Y在首个正式版本发布后执行一次 lineage 同步。此外文档明确要求如当前流程发生调整应同步更新本文档确保 SOP 与仓库实际发版实践始终一致。八、源码级佐证版本管理实现与发布流程的对应关系SOP 中的版本约束在仓库构建链中有完整实现支撑理解这些细节有助于在发版时准确定位需要修改的文件1. 版本号来源与标签格式绑定。paddleocr/_version.py 通过importlib.metadata.version(__package__)从已安装的包元数据读取版本号而该元数据由 pyproject.toml 中的[tool.setuptools_scm]从 git 历史推导version_scheme release-branch-semvergit describe --tags --match v[0-9]*。因此 SOP 强调的正式标签必须为vX.Y.Z不仅是规范要求更是版本号能否正确生成的技术前提——标签缺失或格式不符会导致版本号解析异常。2. 版本号增量机制。pyproject.toml 中version字段声明为dynamic [version]并在注释中说明每次版本发布后需要递增版本号paddleocr/__init__.py中通过from ._version import version as __version__将版本号导出为包的公开属性。发版流程的第 4 步版本号符合预期即可通过该属性或pip show paddleocr验证。3. 依赖约束与发版强绑定。pyproject.toml 的dependencies与全部[project.optional-dependencies]组均以3.7.0,3.8.0的区间锁定paddlex对应 SOP 第 7 步检查 paddlex 依赖约束是否与本次发布版本匹配。从源码结构看PaddleOCR 3.x 的推理、部署能力融合了 PaddleX 底层能力见 docs/version3.x/paddleocr_and_paddlex.md因此 paddlex 依赖区间是发布时必须人工核对的关键约束。4. 发布内容的验证载体。仓库提供多层次的验证入口供发布前检查使用单元与集成测试位于 tests/推理/训练/部署一体化验证脚本位于 test_tipc/含 Python 与 C 推理、Paddle2ONNX、服务化部署等场景的测试脚本模型训练入口位于 tools/train.py。这些正是 SOP 第 4 步必要的测试、构建、打包和回归通过的落点。结语PaddleOCR 的 Release SOP 用一套简洁、明确、可重复的规则管理了开发—发布—维护的全生命周期main 持续集成新特性release/X.Y承载稳定发布vX.Y.Z标签与 setuptools_scm 版本推导技术绑定paddlex 依赖区间与文档版本在每次发布时人工核对lineage 同步保证 main 对版本线状态感知一致。对任何参与 PaddleOCR 维护或希望理解其发布治理模式的开发者而言这份文档既是操作手册也是理解仓库工程化程度的重要入口。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PaddleOCR Release SOP 发版流程全解：从分支模型到 `vX.Y.Z` 标签的九步标准操作
PaddleOCR Release SOP 发版流程全解从分支模型到vX.Y.Z标签的九步标准操作【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本篇指南完整解读 PaddleOCR 仓库中维护的官方发版规范RELEASING.md另有中文版系统讲解其main 日常开发 release/X.Y 正式发布的分支模型、patch/minor/major 三种版本类型的处理边界以及从确认目标到标签发布、依赖约束更新、lineage 同步回 main 的完整九步流程。读完本文你将掌握 PaddleOCR 版本线的组织方式、如何正确从 main 挑选内容、如何在 release 分支打正式标签以及发布前后需要核对的全部检查项可直接用于指导实际发版操作。一、文档定位与适用范围RELEASING.mdRelease SOPStandard Operating Procedure是 PaddleOCR 仓库中描述标准发版流程的规范文档与仓库根目录下的 RELEASING_cn.md 为同一份内容的英文/中文双语文档。它面向的是 PaddleOCR 的维护者与发布负责人回答的核心问题是一次官方版本发布应该走什么样的分支、打什么样的标签、做哪些检查、发完以后还要做什么。该文档不涉及具体 OCR 算法的实现而是聚焦于工程发布治理版本类型、分支模型、cherry-pick 内容挑选、发布前检查、正式标签规范、GitHub Release 创建、依赖约束与文档版本对齐以及 release 分支 lineage 向 main 的同步。二、版本类型patch 与 minor 的明确边界SOP 明确当前流程支持两类发布bump版本类型示例语义bump patch3.4.0 - 3.4.1在既有版本线内发布补丁版本bump minor3.4.x - 3.5.0开启一条新的版本线发布下一阶段稳定版本对于bump majorSOP 给出明确结论当前流程暂不支持直接覆盖。如果需要发布大版本必须单独讨论并设计额外流程例如引入额外分支或新的版本准备方式在新方案明确之前不建议直接套用 minor/patch 的做法处理 major 发布。从仓库实际版本历史见 docs/update/update.md可以印证这一模型的运行方式PaddleOCR 3.x 系列以 minor 版本3.0.0、3.1.0、3.2.0开启新版本线再以 patch 版本3.0.1、3.0.2、3.0.3、3.1.1在同一版本线上发布修复与稳定性更新。三、发版原则双分支模型SOP 明确规定的分支与标签纪律是整套流程的基石日常开发在main分支进行——所有新功能、新模型、新产线的开发先合入 main正式发布只在release/X.Y分支进行——每个 minor 版本线对应一条固定的发布分支正式标签只使用vX.Y.Z格式例如v3.4.1、v3.5.0不在main分支打正式发布标签也不使用开发态标签作为正式发布标签。这种模型保证 main 始终处于持续演进状态而 release 分支保持稳定、可追溯任何时刻都能从 release 分支产出可复现的官方版本。四、标准发版流程九步详解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上完成发布前检查至少应包括当前分支正确工作区干净无未提交改动版本号符合预期关键功能验证通过必要的测试、构建、打包和回归通过发布说明已经准备好。对应到本仓库可在 release 分支上确认paddleocr/_version.py读取到的版本信息与目标一致并运行仓库测试目录如 tests/、test_tipc/中的相关测试与回归用例。5. 打正式标签确认版本 ready 后在release/X.Y分支上打正式标签格式必须为vX.Y.Z例如v3.4.1、v3.5.0。要求标签必须打在本次正式发布对应的 release 分支上不使用开发态标签作为正式发布标签。值得补充的是标签格式与版本号解析在仓库构建链中是强耦合的pyproject.toml 中[tool.setuptools_scm]配置了version_scheme release-branch-semver并要求git describe时匹配v[0-9]*前缀的标签。也就是说正式标签命名直接决定了 setuptools_scm 能否从 git 历史推导出正确的发布版本号这也解释了 SOP 为何将vX.Y.Z格式列为硬性要求。6. 发布 GitHub Release在 GitHub 上基于本次正式标签创建 Release发布说明应与此前的发布准备对齐。7. 更新依赖约束与发布说明如果本次发布是新的 minor 版本首发或本次发布涉及 PaddleX 依赖变化则在正式标签发布前后同步完成相关更新至少包括检查pyproject.toml中paddlex相关依赖约束是否与本次发布版本匹配检查安装说明、升级说明和发布说明中的版本信息是否与本次发布一致。完成要求paddlex相关依赖约束与本次发布目标一致文档中的版本信息与本次发布版本一致。这一步在源码中有非常直接的对应物当前 pyproject.toml 的dependencies中声明了paddlex[ocr-core]3.7.0,3.8.0各可选依赖组doc-parser、ie、trans、all同样以上下界约束锁定 paddlex 版本。发版时若目标版本与 paddlex 依赖区间不符必须同步调整该文件。同时需要核对的文档包括 docs/version3.x/installation.md安装说明、docs/update/upgrade_notes.md升级说明以及 docs/update/update.md更新日志。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。SOP 中的 1~4、6、9 步在该场景下按需复用。Minor 发布适用场景开启一条新的发布线发布下一阶段稳定版本例如3.5.0。处理方式对应完整的九步流程从main建立新的release/X.Y按标准流程准备版本内容cherry-pick打首个正式标签例如v3.5.0如有需要同步更新paddlex相关依赖约束第 7 步发布后将该 release 分支的 lineage 同步回main第 8 步。Major 发布当前结论暂不纳入本 SOP后续需要单独讨论并设计流程。在新的方案明确之前不建议直接套用当前 minor/patch 的做法处理 major 发布。这与 2.x - 3.x 的实际演进路径相互印证——3.0 是脱离常规补丁节奏、专门设计的大版本升级背景与动机详见 docs/update/upgrade_notes.md。六、发布检查清单每次发版前SOP 要求确认以下事项已确认目标版本号和对应 release 分支release 分支中的内容已经 ready发布范围已经收敛关键测试和回归已通过发布说明已准备完成正式标签格式为vX.Y.ZGitHub Release 已创建如本次是该release/X.Y的首个正式版本发布完成后已将 lineage 同步回main。七、日常维护建议SOP 给出的日常维护准则可以概括为四条新功能优先进入main正式发布始终通过release/X.Y执行补丁版本始终在对应的release/X.Y上维护每条新的release/X.Y在首个正式版本发布后执行一次 lineage 同步。此外文档明确要求如当前流程发生调整应同步更新本文档确保 SOP 与仓库实际发版实践始终一致。八、源码级佐证版本管理实现与发布流程的对应关系SOP 中的版本约束在仓库构建链中有完整实现支撑理解这些细节有助于在发版时准确定位需要修改的文件1. 版本号来源与标签格式绑定。paddleocr/_version.py 通过importlib.metadata.version(__package__)从已安装的包元数据读取版本号而该元数据由 pyproject.toml 中的[tool.setuptools_scm]从 git 历史推导version_scheme release-branch-semvergit describe --tags --match v[0-9]*。因此 SOP 强调的正式标签必须为vX.Y.Z不仅是规范要求更是版本号能否正确生成的技术前提——标签缺失或格式不符会导致版本号解析异常。2. 版本号增量机制。pyproject.toml 中version字段声明为dynamic [version]并在注释中说明每次版本发布后需要递增版本号paddleocr/__init__.py中通过from ._version import version as __version__将版本号导出为包的公开属性。发版流程的第 4 步版本号符合预期即可通过该属性或pip show paddleocr验证。3. 依赖约束与发版强绑定。pyproject.toml 的dependencies与全部[project.optional-dependencies]组均以3.7.0,3.8.0的区间锁定paddlex对应 SOP 第 7 步检查 paddlex 依赖约束是否与本次发布版本匹配。从源码结构看PaddleOCR 3.x 的推理、部署能力融合了 PaddleX 底层能力见 docs/version3.x/paddleocr_and_paddlex.md因此 paddlex 依赖区间是发布时必须人工核对的关键约束。4. 发布内容的验证载体。仓库提供多层次的验证入口供发布前检查使用单元与集成测试位于 tests/推理/训练/部署一体化验证脚本位于 test_tipc/含 Python 与 C 推理、Paddle2ONNX、服务化部署等场景的测试脚本模型训练入口位于 tools/train.py。这些正是 SOP 第 4 步必要的测试、构建、打包和回归通过的落点。结语PaddleOCR 的 Release SOP 用一套简洁、明确、可重复的规则管理了开发—发布—维护的全生命周期main 持续集成新特性release/X.Y承载稳定发布vX.Y.Z标签与 setuptools_scm 版本推导技术绑定paddlex 依赖区间与文档版本在每次发布时人工核对lineage 同步保证 main 对版本线状态感知一致。对任何参与 PaddleOCR 维护或希望理解其发布治理模式的开发者而言这份文档既是操作手册也是理解仓库工程化程度的重要入口。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考