PaddleOCR 发版 SOP 全解析基于 main 与 release/X.Y 分支的标准化版本发布流程【免费下载链接】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/PaddleOCRPaddleOCR 作为飞桨生态的多语言 OCR 与文档解析工具包其版本发布需要兼顾日常开发、补丁修复与多版本线长期维护之间的平衡。本文以仓库根目录 RELEASING_cn.md 中的标准发版流程Release SOP为核心完整讲解 PaddleOCR 的版本类型划分、九步标准发版流程、patch/minor/major 三类 bump 的处理差异并结合仓库源码如 pyproject.toml、paddleocr/_version.py说明版本号与依赖约束在发布流程中的实际落点。读完本文你将掌握一套可直接复用的日常开发在 main、正式发布走 release/X.Y、标签严格使用 vX.Y.Z的分支与版本治理方案。一、文档适用范围与定位RELEASING_cn.md英文版见 RELEASING.md是 PaddleOCR 维护者执行标准发版流程的操作手册SOP核心目标是让何时发版、在哪个分支发版、如何打标签、发版后如何同步这些动作具备统一的、可重复执行的规范避免因分支混用或标签不规范导致版本线混乱。该 SOP 面向的对象包括负责 PaddleOCR 版本发布的维护者、需要理解仓库分支策略与版本节奏的贡献者以及希望基于 PaddleOCR 进行二次分发或私有定制并同步上游版本的用户。二、版本类型当前流程支持 patch 与 minorSOP 明确界定了当前流程能够支撑的两类版本发布版本类型含义示例bump patch在同一版本线内的补丁版本递增3.4.0 - 3.4.1bump minor开启新版本线的小版本发布3.4.x - 3.5.0需要特别说明的是bump major大版本发布当前流程暂不支持直接覆盖此类场景。若需发布大版本需要单独讨论并设计额外流程例如引入额外分支或新的版本准备方式。这一点在仓库中同样有迹可循——docs/update/upgrade_notes.md 记录了 PaddleOCR 从 2.x 跨越到 3.x 的重大非兼容升级背景可见 major 版本升级往往伴随架构级改造确实需要独立于常规 SOP 的专项方案。三、发版原则四条红线整个 SOP 建立在四条分支与标签管理原则上这是所有后续步骤的前提日常开发在main分支进行main是唯一承载新功能与常规开发的集成分支正式发布只在release/X.Y分支进行每个 minor 版本线对应一个固定形如release/3.4、release/3.5的发布分支正式标签只使用vX.Y.Z例如v3.4.1、v3.5.0不在main分支打正式发布标签正式标签必须落在对应的 release 分支上。仓库文档中也体现了这一分支策略的落地。例如 docs/version3.x/installation.md 在介绍源码安装时明确给出git checkout release/3.5的示例说明从源码安装稳定版本时用户被引导到对应的 release 分支而非main。四、标准发版流程九步全解析SOP 将一次完整发版拆解为九个步骤下面按顺序逐一展开并补充每一步背后的工程考量。步骤 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 挑选发布内容cherry-pick根据本次发布范围从main将需要发布的提交按需cherry-pick到release/X.Y直到版本内容 ready。要求只挑选本次发布需要的内容避免把与本次发布无关的新功能带入 release 分支如果 release 分支上出现专门的发布修复也应仅限于本次发布范围通过按需挑选而非整支合并的方式保证发布范围收敛、可审计。步骤 4完成发布前检查在release/X.Y上完成发布前检查至少应包括当前分支正确工作区干净版本号符合预期关键功能验证通过必要的测试、构建、打包和回归通过发布说明已经准备好。其中版本号符合预期这一项在仓库中与版本管理机制直接相关。PaddleOCR 的版本号采用动态解析而非硬编码paddleocr/_version.py 通过importlib.metadata.version(__package__)读取已安装包的元数据获取版本若包未安装则回退为0.0.0而 pyproject.toml 中声明dynamic [version]并借助setuptools_scm的release-branch-semver版本方案通过git describe --dirty --tags --long --match v[0-9]*从 git 标签推导版本号。这意味着正式标签vX.Y.Z的命名会直接影响构建产物的版本号解析步骤 4 中版本号符合预期与步骤 5标签格式必须为 vX.Y.Z在工程上是强耦合的。步骤 5打正式标签确认版本 ready 后在release/X.Y分支上打正式标签标签格式必须为vX.Y.Z示例v3.4.1、v3.5.0。要求标签必须打在本次正式发布对应的 release 分支上不使用开发态标签作为正式发布标签。步骤 6发布 GitHub Release在 GitHub 上基于本次正式标签创建 Release将步骤 5 打出的vX.Y.Z标签与对外发布的 Release 页面对齐。步骤 7更新依赖约束与发布说明如果本次发布是新的 minor 版本首发或本次发布涉及 PaddleX 依赖变化则在正式标签发布前后同步完成相关更新。至少应包括检查 pyproject.toml 中paddlex相关依赖约束是否与本次发布版本匹配检查安装说明、升级说明和发布说明中的版本信息是否与本次发布一致。完成要求paddlex相关依赖约束与本次发布目标一致文档中的版本信息与本次发布版本一致。从仓库源码看paddlex依赖约束在 pyproject.toml 中有多处体现核心依赖paddlex[ocr-core]3.7.0,3.8.0可选依赖组doc-parser [paddlex[ocr,genai-client]3.7.0,3.8.0]、ie [paddlex[ie]3.7.0,3.8.0]、trans [paddlex[trans]3.7.0,3.8.0]、all [paddlex[ocr,genai-client,ie,trans]3.7.0,3.8.0, ...]。也就是说当 PaddleOCR 发布新版本时维护者需要同步核对这些约束中的上下界当前仓库中为3.7.0,3.8.0是否与目标发布所依赖的 PaddleX 版本一致同时更新 docs/version3.x/installation.md、docs/update/upgrade_notes.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。补丁发布不新建分支、不新增发布线全部工作在既有 release 分支上完成这也是补丁版本始终在对应的release/X.Y上维护这一日常维护建议的体现。Minor 发布适用场景开启一条新的发布线发布下一阶段稳定版本例如3.5.0。处理方式从main建立新的release/X.Y按标准流程准备版本内容打首个正式标签例如v3.5.0如有需要同步更新paddlex相关依赖约束发布后将该 release 分支的 lineage 同步回main。Minor 发布是完整走完九步 SOP 的典型场景其中步骤 7依赖约束与步骤 8lineage 同步只有在 minor 首发时才必须执行。Major 发布当前结论暂不纳入本 SOP后续需要单独讨论并设计流程。在新的方案明确之前不建议直接套用当前 minor/patch 的做法处理 major 发布。如 docs/update/upgrade_notes.md 所示PaddleOCR 历史上 2.x 到 3.x 的升级涉及架构重构、依赖体系调整与非兼容性变更这类发布显然需要独立的专项流程支撑。六、发布检查清单发版前的最终确认每次发版前请确认以下事项已确认目标版本号和对应 release 分支release 分支中的内容已经 ready发布范围已经收敛关键测试和回归已通过发布说明已准备完成正式标签格式为vX.Y.ZGitHub Release 已创建如本次是该release/X.Y的首个正式版本发布完成后已将 lineage 同步回main。这份清单本质上是九步流程中检查类动作的浓缩建议维护者将其作为发版 PR 的模板化核对项。七、日常维护建议新功能优先进入main正式发布始终通过release/X.Y执行补丁版本始终在对应的release/X.Y上维护每条新的release/X.Y在首个正式版本发布后执行一次 lineage 同步。如当前流程发生调整应同步更新本文档即 RELEASING_cn.md 与其英文版 RELEASING.md。八、流程要点速览与源码佐证为便于快速查阅将整个 SOP 的核心结论汇总如下维度规范开发分支main承载日常开发与全部新功能发布分支release/X.Y一个 minor 版本线对应一个固定分支正式标签vX.Y.Z只能打在 release 分支上内容流入从main按发布范围cherry-pick到 release 分支版本类型patch3.4.0 - 3.4.1、minor3.4.x - 3.5.0major 暂不纳入 SOP依赖同步新 minor 首发或涉及 PaddleX 变化时核对 pyproject.toml 中paddlex约束并更新安装/升级/发布说明分支同步每条新 release 线首个正式版本发布后将 lineage 同步回main版本号机制pyproject.toml 声明dynamic [version]由setuptools_scm依据v[0-9]*标签推导paddleocr/_version.py 通过importlib.metadata.version读取从源码结构看PaddleOCR 的版本治理形成了完整的证据链标签命名规范vX.Y.Z→ setuptools_scm 版本推导pyproject.toml 中git_describe_command匹配v[0-9]*→ 运行时版本读取paddleocr/_version.py→ 依赖约束声明paddlex[ocr-core]3.7.0,3.8.0→ 文档版本同步docs/version3.x/installation.md 中git checkout release/3.5示例。这正是 RELEASING SOP 之所以能落地的工程基础。对于社区贡献者而言理解这套 SOP 的意义在于提交新功能时优先合入main遇到需要进入稳定版本的修复时维护者会按需 cherry-pick 到对应 release 分支对于希望长期跟进特定稳定版本的集成方则应基于release/X.Y分支而非main构建以保证依赖约束与文档版本的一致性。【免费下载链接】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 发版 SOP 全解析：基于 main 与 release/X.Y 分支的标准化版本发布流程
PaddleOCR 发版 SOP 全解析基于 main 与 release/X.Y 分支的标准化版本发布流程【免费下载链接】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/PaddleOCRPaddleOCR 作为飞桨生态的多语言 OCR 与文档解析工具包其版本发布需要兼顾日常开发、补丁修复与多版本线长期维护之间的平衡。本文以仓库根目录 RELEASING_cn.md 中的标准发版流程Release SOP为核心完整讲解 PaddleOCR 的版本类型划分、九步标准发版流程、patch/minor/major 三类 bump 的处理差异并结合仓库源码如 pyproject.toml、paddleocr/_version.py说明版本号与依赖约束在发布流程中的实际落点。读完本文你将掌握一套可直接复用的日常开发在 main、正式发布走 release/X.Y、标签严格使用 vX.Y.Z的分支与版本治理方案。一、文档适用范围与定位RELEASING_cn.md英文版见 RELEASING.md是 PaddleOCR 维护者执行标准发版流程的操作手册SOP核心目标是让何时发版、在哪个分支发版、如何打标签、发版后如何同步这些动作具备统一的、可重复执行的规范避免因分支混用或标签不规范导致版本线混乱。该 SOP 面向的对象包括负责 PaddleOCR 版本发布的维护者、需要理解仓库分支策略与版本节奏的贡献者以及希望基于 PaddleOCR 进行二次分发或私有定制并同步上游版本的用户。二、版本类型当前流程支持 patch 与 minorSOP 明确界定了当前流程能够支撑的两类版本发布版本类型含义示例bump patch在同一版本线内的补丁版本递增3.4.0 - 3.4.1bump minor开启新版本线的小版本发布3.4.x - 3.5.0需要特别说明的是bump major大版本发布当前流程暂不支持直接覆盖此类场景。若需发布大版本需要单独讨论并设计额外流程例如引入额外分支或新的版本准备方式。这一点在仓库中同样有迹可循——docs/update/upgrade_notes.md 记录了 PaddleOCR 从 2.x 跨越到 3.x 的重大非兼容升级背景可见 major 版本升级往往伴随架构级改造确实需要独立于常规 SOP 的专项方案。三、发版原则四条红线整个 SOP 建立在四条分支与标签管理原则上这是所有后续步骤的前提日常开发在main分支进行main是唯一承载新功能与常规开发的集成分支正式发布只在release/X.Y分支进行每个 minor 版本线对应一个固定形如release/3.4、release/3.5的发布分支正式标签只使用vX.Y.Z例如v3.4.1、v3.5.0不在main分支打正式发布标签正式标签必须落在对应的 release 分支上。仓库文档中也体现了这一分支策略的落地。例如 docs/version3.x/installation.md 在介绍源码安装时明确给出git checkout release/3.5的示例说明从源码安装稳定版本时用户被引导到对应的 release 分支而非main。四、标准发版流程九步全解析SOP 将一次完整发版拆解为九个步骤下面按顺序逐一展开并补充每一步背后的工程考量。步骤 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 挑选发布内容cherry-pick根据本次发布范围从main将需要发布的提交按需cherry-pick到release/X.Y直到版本内容 ready。要求只挑选本次发布需要的内容避免把与本次发布无关的新功能带入 release 分支如果 release 分支上出现专门的发布修复也应仅限于本次发布范围通过按需挑选而非整支合并的方式保证发布范围收敛、可审计。步骤 4完成发布前检查在release/X.Y上完成发布前检查至少应包括当前分支正确工作区干净版本号符合预期关键功能验证通过必要的测试、构建、打包和回归通过发布说明已经准备好。其中版本号符合预期这一项在仓库中与版本管理机制直接相关。PaddleOCR 的版本号采用动态解析而非硬编码paddleocr/_version.py 通过importlib.metadata.version(__package__)读取已安装包的元数据获取版本若包未安装则回退为0.0.0而 pyproject.toml 中声明dynamic [version]并借助setuptools_scm的release-branch-semver版本方案通过git describe --dirty --tags --long --match v[0-9]*从 git 标签推导版本号。这意味着正式标签vX.Y.Z的命名会直接影响构建产物的版本号解析步骤 4 中版本号符合预期与步骤 5标签格式必须为 vX.Y.Z在工程上是强耦合的。步骤 5打正式标签确认版本 ready 后在release/X.Y分支上打正式标签标签格式必须为vX.Y.Z示例v3.4.1、v3.5.0。要求标签必须打在本次正式发布对应的 release 分支上不使用开发态标签作为正式发布标签。步骤 6发布 GitHub Release在 GitHub 上基于本次正式标签创建 Release将步骤 5 打出的vX.Y.Z标签与对外发布的 Release 页面对齐。步骤 7更新依赖约束与发布说明如果本次发布是新的 minor 版本首发或本次发布涉及 PaddleX 依赖变化则在正式标签发布前后同步完成相关更新。至少应包括检查 pyproject.toml 中paddlex相关依赖约束是否与本次发布版本匹配检查安装说明、升级说明和发布说明中的版本信息是否与本次发布一致。完成要求paddlex相关依赖约束与本次发布目标一致文档中的版本信息与本次发布版本一致。从仓库源码看paddlex依赖约束在 pyproject.toml 中有多处体现核心依赖paddlex[ocr-core]3.7.0,3.8.0可选依赖组doc-parser [paddlex[ocr,genai-client]3.7.0,3.8.0]、ie [paddlex[ie]3.7.0,3.8.0]、trans [paddlex[trans]3.7.0,3.8.0]、all [paddlex[ocr,genai-client,ie,trans]3.7.0,3.8.0, ...]。也就是说当 PaddleOCR 发布新版本时维护者需要同步核对这些约束中的上下界当前仓库中为3.7.0,3.8.0是否与目标发布所依赖的 PaddleX 版本一致同时更新 docs/version3.x/installation.md、docs/update/upgrade_notes.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。补丁发布不新建分支、不新增发布线全部工作在既有 release 分支上完成这也是补丁版本始终在对应的release/X.Y上维护这一日常维护建议的体现。Minor 发布适用场景开启一条新的发布线发布下一阶段稳定版本例如3.5.0。处理方式从main建立新的release/X.Y按标准流程准备版本内容打首个正式标签例如v3.5.0如有需要同步更新paddlex相关依赖约束发布后将该 release 分支的 lineage 同步回main。Minor 发布是完整走完九步 SOP 的典型场景其中步骤 7依赖约束与步骤 8lineage 同步只有在 minor 首发时才必须执行。Major 发布当前结论暂不纳入本 SOP后续需要单独讨论并设计流程。在新的方案明确之前不建议直接套用当前 minor/patch 的做法处理 major 发布。如 docs/update/upgrade_notes.md 所示PaddleOCR 历史上 2.x 到 3.x 的升级涉及架构重构、依赖体系调整与非兼容性变更这类发布显然需要独立的专项流程支撑。六、发布检查清单发版前的最终确认每次发版前请确认以下事项已确认目标版本号和对应 release 分支release 分支中的内容已经 ready发布范围已经收敛关键测试和回归已通过发布说明已准备完成正式标签格式为vX.Y.ZGitHub Release 已创建如本次是该release/X.Y的首个正式版本发布完成后已将 lineage 同步回main。这份清单本质上是九步流程中检查类动作的浓缩建议维护者将其作为发版 PR 的模板化核对项。七、日常维护建议新功能优先进入main正式发布始终通过release/X.Y执行补丁版本始终在对应的release/X.Y上维护每条新的release/X.Y在首个正式版本发布后执行一次 lineage 同步。如当前流程发生调整应同步更新本文档即 RELEASING_cn.md 与其英文版 RELEASING.md。八、流程要点速览与源码佐证为便于快速查阅将整个 SOP 的核心结论汇总如下维度规范开发分支main承载日常开发与全部新功能发布分支release/X.Y一个 minor 版本线对应一个固定分支正式标签vX.Y.Z只能打在 release 分支上内容流入从main按发布范围cherry-pick到 release 分支版本类型patch3.4.0 - 3.4.1、minor3.4.x - 3.5.0major 暂不纳入 SOP依赖同步新 minor 首发或涉及 PaddleX 变化时核对 pyproject.toml 中paddlex约束并更新安装/升级/发布说明分支同步每条新 release 线首个正式版本发布后将 lineage 同步回main版本号机制pyproject.toml 声明dynamic [version]由setuptools_scm依据v[0-9]*标签推导paddleocr/_version.py 通过importlib.metadata.version读取从源码结构看PaddleOCR 的版本治理形成了完整的证据链标签命名规范vX.Y.Z→ setuptools_scm 版本推导pyproject.toml 中git_describe_command匹配v[0-9]*→ 运行时版本读取paddleocr/_version.py→ 依赖约束声明paddlex[ocr-core]3.7.0,3.8.0→ 文档版本同步docs/version3.x/installation.md 中git checkout release/3.5示例。这正是 RELEASING SOP 之所以能落地的工程基础。对于社区贡献者而言理解这套 SOP 的意义在于提交新功能时优先合入main遇到需要进入稳定版本的修复时维护者会按需 cherry-pick 到对应 release 分支对于希望长期跟进特定稳定版本的集成方则应基于release/X.Y分支而非main构建以保证依赖约束与文档版本的一致性。【免费下载链接】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），仅供参考