PaddleOCR 开源贡献实战Python 代码规范、文档规范与完整 Pull Request 流程【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本文基于 PaddleOCR 官方文档站“附录”docs/community/code_and_doc.md整理系统讲解为 PaddleOCR 贡献代码与文档前必须掌握的三件事遵循 PEP8 的 Python 代码风格、中英双语文档的书写规范以及从 Fork 仓库到 PR 合入、分支清理的完整提交流程。读完并照着操作一遍后你可以独立完成一个格式合规、通过 pre-commit 检查、可直接提交 Review 的 PaddleOCR Pull Request。在 PaddleOCR 文档站中本附录与 社区贡献指南 配套使用前者回答“贡献什么、找谁对接”后者回答“代码怎么写、文档怎么排、PR 怎么提”。两者均在 mkdocs.yml 的导航中注册第 440441 行社区贡献与附录两个条目并通过 mkdocs-material 主题渲染成线。1. Python 代码规范PEP8PaddleOCR 的 Python 代码遵循 PEP8 规范官方文档在其中重点强调空格与注释两部分。这部分内容适用于仓库内 ppocr/、tools/、paddleocr/ 等所有 Python 源码目录Python 版本要求见 pyproject.tomlrequires-python 3.8。1.1 空格规则逗号、分号、冒号空格应加在这些符号之后而不是之前。# 正确 print(x, y) # 错误 print(x , y)关键字参数与默认参数在函数定义中指定关键字参数或默认参数值时等号两侧不要使用空格。# 正确 def complex(real, imag0.0): ... # 错误 def complex(real, imag 0.0): ...这条规则与仓库的自动检查一致.pre-commit-config.yaml 中集成了blackrev 24.10.0负责 Python 格式化flake8rev 7.1.1负责静态检查参数为--selectE9,F63,F7,F82,E721即只拦截语法错误、未定义名称等硬性问题见 第 3046 行而风格细节主要由 black 统一处理。1.2 注释规范行内注释使用#表示代码与#之间空两个空格#与注释内容之间空一个空格。x x 1 # Compensate for border函数/方法文档字符串每个函数定义后的 docstring 应包含三部分——函数描述函数的作用、输入输出Args每个参数名及其含义Returns返回值的含义和类型。官方给出的标准范例def fetch_bigtable_rows(big_table, keys, other_silly_variableNone): Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {Serak: (Rigel VII, Preparer), Zim: (Irk, Invader), Lrrr: (Omicron Persei 8, Emperor)} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. pass从源码结构看仓库中较新的 paddleocr/_utils/、mcp_server/ 等模块的公共函数普遍采用这种“描述 Args Returns”的三段式 docstring贡献新模块时保持一致的注释风格即可与现有代码无缝融合。2. 文档规范为 PaddleOCR 贡献文档新增算法说明、部署指南等时需要遵守以下规范。当前仓库的文档位于 docs/ 目录例如 docs/version3.x/ 下的流水线与模型使用文档即为典型结构。2.1 总体说明文档位置如果新增功能可以补充到原有的 Markdown 文件中请不要重新新建一个文件对添加位置不清楚时可以先提 PR然后在 commit 中询问官方人员。新增文档命名用英文描述文档内容一般由小写字母与下划线组合例如add_new_algorithm.md。新增文档格式目录 - 正文 - FAQ 三段式结构。目录可以用 Markdown TOC 生成工具自动生成并在每个标题前插入。中英双语任何对文档的改动或新增都需要同时在中文和英文文档上进行。这一点在仓库中可以直接验证社区目录下 code_and_doc.md 与 code_and_doc.en.md、community_contribution.md 与 community_contribution.en.md 均成对存在各文档目录同样普遍采用xxx.mdxxx.en.md的双语配对。2.2 格式规范标题格式阿拉伯数字小数点组合 - 空格 - 标题例如2.1 XXXX、2. XXXX。代码块用代码块展示需要运行的代码并在代码块前用一段话描述命令参数的含义。官方示例检测方向分类器识别全流程设置方向分类器参数--use_angle_cls true后可对竖排文本进行识别。paddleocr --image_dir ./imgs/11.jpg --use_angle_cls true变量引用行内引用代码变量或命令参数时用行内代码表示例如--use_angle_cls true前后各空一格。统一命名如 PP-OCRv2、PP-OCR mobile、paddleocrwhl 包、PPOCRLabel、Paddle Lite 等专有名词保持统一写法。补充说明通过引用格式补充说明或标注注意事项。图片新增图片要规范命名描述图片内容并将图片放在doc/下。3. 分支模型release 与开发分支的分工附录 3 对 PaddleOCR 的分支策略给出如下说明以文档原文为准release/x.x 系列分支稳定的发行版本分支也是默认分支。PaddleOCR 根据功能更新情况发布新的 release 分支同时适配 Paddle 的 release 版本。随着版本迭代release/x.x 系列分支会越来越多默认维护最新版本的 release 分支。dygraph 分支开发分支适配 Paddle 动态图版本主要用于开发新功能。二次开发应选择该分支。为保证 dygraph 分支需要时能拉出 release/x.x 分支dygraph 分支只能使用 Paddle 最新 release 分支中已有效的 API——如果 Paddle dygraph 分支中的新 API 尚未出现在 release 分支中不要在 PaddleOCR 中使用。不涉及 API 的性能优化、参数调整、策略更新等可以正常开发。develop 分支历史分支不再更新曾用于静态图的开发与测试兼容 1.7 版本的 Paddle除修复 bug 外不再更新代码。需要说明的适用前提当前仓库快照的默认分支为mainGit 远程 HEAD 指向main。上述 dygraph/develop 的分工描述来自官方附录文档反映项目早期版本维护期的分支策略实际贡献前请以目标仓库当前分支命名和 PR 要求为准流程Fork、分支、pre-commit、PR本身不受影响。4. 代码提交流程详解熟悉 Git 的读者可直接跳到 4.10 提交代码的一些约定。以下流程完整继承自附录 3.2 节命令均可直接复制使用将{your_name}、{token}替换为自己的值。4.1 创建你的远程仓库Fork在 PaddleOCR 项目主页点击Fork按钮在自己的个人目录下创建远程仓库例如https://github.com/{your_name}/PaddleOCR。将远程仓库 clone 到本地# 拉取开发分支的代码 git clone https://github.com/{your_name}/PaddleOCR.git -b dygraph cd PaddleOCR多数情况下 clone 失败是网络原因请稍后重试或配置代理。4.2 通过 Token 方式登录与建立连接首先查看当前远程仓库信息git remote -v # origin https://github.com/{your_name}/PaddleOCR.git (fetch) # origin https://github.com/{your_name}/PaddleOCR.git (push)由于 GitHub 登录方式变化需要通过 Token 重新配置远程仓库地址。生成 Token在 GitHub 页面右上角点击头像依次选择 Settings → Developer settings → Personal access tokens点击 Generate new token在 Note 中填入名称例如paddleSelect scopes 勾选repo必选、admin:repo_hook、delete_repo等按需选择后点击 Generate token并复制生成的 token。删除原始 origin 配置再添加带 Token 的 origingit remote rm origin将 remote 改成https://oauth2:{token}github.com/{your_name}/PaddleOCR.git的形式。例如 token 值为12345、用户名为PPOCR则git remote add origin https://oauth2:12345github.com/PPOCR/PaddleOCR.git接下来创建原始 PaddleOCR 仓库的远程主机命名为upstreamgit remote add upstream https://github.com/PaddlePaddle/PaddleOCR.git再次git remote -v查看输出应包含 origin 和 upstream 两个远程仓库origin https://oauth2:{token}github.com/{your_name}/PaddleOCR.git (fetch) origin https://oauth2:{token}github.com/{your_name}/PaddleOCR.git (push) upstream https://github.com/PaddlePaddle/PaddleOCR.git (fetch) upstream https://github.com/PaddlePaddle/PaddleOCR.git (push)这一步的意义在于后续提交 PR 时可以随时从 upstream 同步上游最新代码保持本地仓库最新。4.3 创建本地分支获取 upstream 最新代码基于上游仓库的开发分支创建new_branchgit fetch upstream git checkout -b new_branch upstream/dygraph如果新 Fork 的 PaddleOCR 项目中用户远程仓库origin与上游upstream的分支更新情况相同也可以基于 origin 创建分支# 基于用户远程仓库(origin)的dygraph创建new_branch分支 git checkout -b new_branch origin/dygraph # 基于用户远程仓库(origin)的默认分支创建new_branch分支 git checkout -b new_branch成功后会输出切换信息Branch new_branch set up to track remote branch develop from upstream. Switched to a new branch new_branch切换之后即可在该分支上进行文件改动。4.4 使用 pre-commit 钩子PaddleOCR 使用 pre-commit 工具管理 Git 预提交钩子帮助格式化源代码C、Python并在 commit 前自动检查基本事项如每个文件只有一个 EOL、Git 中不添加大文件等。pre-commit 检查是 CI 单元测试的一部分不满足钩子要求的 PR 无法合入 PaddleOCR。安装并在当前目录运行pip install pre-commit pre-commit installC/C 源代码格式调整使用 clang-format请确保clang-format版本在 3.8 以上。通过pip install pre-commit与conda install -c conda-forge pre-commit安装的钩子环境略有不同PaddleOCR 开发约定使用pip install pre-commit。仓库中的实际钩子配置.pre-commit-config.yaml可供对照当前配置包含钩子作用说明check-added-large-files拦截大文件限制单文件--maxkb512防止误提交模型权重等check-case-conflict/check-merge-conflict/check-symlinks/detect-private-key基础卫生检查文件名大小写冲突、合并冲突标记、符号链接、私钥泄露end-of-file-fixer保证文件以换行结尾统一 EOLtrailing-whitespace/remove-tabs/remove-crlf清理 C/C/Python 文件尾随空白、Tab、CRLF匹配\.(c\|cc\|cxx\|cpp\|cu\|h\|hpp\|hxx\|py)$clang-format格式化 C/C/CUDA 源码调用本地脚本 .clang_format.hookblack格式化 Python 代码rev 24.10.0flake8Python 静态检查rev 7.1.1--selectE9,F63,F7,F82,E721排除 benchmark/ 与 test_tipc/ 目录此外配置首行exclude: ^(langchain-paddleocr/\|paddleocr-js/)表明 langchain-paddleocr/ 与 paddleocr-js/ 两个独立子项目不在主仓库钩子管辖范围内——贡献这两个子项目代码时应关注它们各自的工具链如 paddleocr-js/package.json 中的 lint/test 脚本。4.5 修改与提交代码假设对README.md做了修改查看改动、添加文件然后运行 pre-commit 检查git status # 查看改动文件 git add README.md pre-commit重复上述步骤直到 pre-commit 格式检查不报错然后提交修改并写明修改内容git commit -m your commit info4.6 Push 到远程仓库将修改的 commit 推送到自己的远程仓库git push origin new_branch4.7 提交 Pull Request打开自己的远程仓库界面选择提交的分支点击 new pull request 或 contribute 进入 PR 界面选择本地分支与目标分支如下图所示。在 PR 描述中填写该 PR 完成的功能随后等待 review若需要修改参照上述步骤更新 origin 中的对应分支即可。4.8 签署 CLA 协议和通过单元测试首次向 PaddlePaddle 提交 Pull Request 时需要签署一次 CLAContributor License Agreement协议以保证代码可以合入在 PR 的 Check 部分找到license/cla点击右侧 detail 进入 CLA 网站点击 CLA 网站中的 “Sign in with GitHub to agree”完成后跳转回 Pull Request 页面。同时请保证 Travis-CI或当前项目 CI中的单元测试能顺利通过否则维护人员一般不做评审。4.9 删除分支PR 被 merge 后清理分支。删除远程分支可在 PR 页面直接删除或使用git push origin :new_branch删除本地分支# 切换到dygraph分支否则无法删除当前分支 git checkout dygraph # 删除new_branch分支 git branch -D new_branch4.10 提交代码的一些约定为使维护人员评审时能专注于代码本身提交代码请遵守以下约定保证单元测试通过。如果没通过说明代码存在问题官方维护人员一般不做评审。提交 PR 前注意 commit 数量仅修改一个文件却提交十几个小 commit会迫使评审人逐一查看每个 commit且 commit 间修改可能相互覆盖。建议每次提交保持尽量少的 commit可用git commit --amend补充上一次的 commit对已 push 的多个 commit 可参考 squash 技巧合并。注意每个 commit 的名称应能反映当前 commit 的内容不能太随意。关联 Issue如果解决了某个 Issue请在该 Pull Request 的第一个评论框中加上fix #issue_numberPR 合并后会自动关闭对应 Issue。可用关键词包括close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved请选择合适的词汇。回复评审人意见的约定每一条 review 意见都希望得到回复同意且已按意见修改的回复简单的Done即可不同意的请给出自己的反驳理由。评审意见较多时给出总体修改情况的说明采用start a review批量回复而非逐条直接回复——每条直接回复都会触发一封邮件多条意见会造成“邮件灾难”。5. 小结PaddleOCR 的贡献规范可以归纳为三条主线代码层面以 PEP8 black/flake8/pre-commit 保证风格一致文档层面以“双语 三段式 统一格式”保证可读性流程层面以 Fork → Token 配置 → 功能分支 → pre-commit → PR → CLA/单测 → 清理分支的闭环保证评审效率。仓库内 docs/community/community_contribution.md 提供了贡献入口与联系方式建议通过 issue 标题加【third-party】标记先与官方沟通技术方案与本文的流程规范配合使用即可开始一次完整的开源贡献。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考