PDF-Extract-Kit贡献指南：提交PR的正确方式
PDF-Extract-Kit贡献指南：提交PR的正确方式
1. 贡献前必读
1.1 项目背景与定位
PDF-Extract-Kit 是一个基于深度学习的 PDF 智能提取工具箱，由开发者“科哥”主导二次开发并开源。该项目集成了布局检测、公式识别、OCR 文字提取、表格解析等核心功能，旨在为科研人员、教育工作者和文档处理从业者提供高效、精准的 PDF 内容结构化解析能力。
作为一个模块化设计的智能文档处理系统，PDF-Extract-Kit 支持 WebUI 交互式操作与 API 扩展调用，底层融合了 YOLO 布局检测模型、PaddleOCR 引擎以及专用公式识别网络，具备良好的可扩展性和工程落地价值。
1.2 开源协作原则
本项目遵循MIT 开源协议，欢迎社区开发者通过 Issue 提交问题、Feature Request 或 Pull Request（PR）参与共建。为了确保代码质量与协作效率，请所有贡献者在提交 PR 前仔细阅读以下规范。
⚠️重要提示：任何未遵循本指南的 PR 将可能被直接关闭或要求重写。
2. 提交PR的标准流程
2.1 环境准备与分支管理
在开始贡献之前，请完成以下准备工作：
# 1. Fork 项目到你的 GitHub 账户 # 2. 克隆 fork 后的仓库 git clone https://github.com/your-username/PDF-Extract-Kit.git cd PDF-Extract-Kit # 3. 添加上游仓库作为远程源（便于同步主干更新） git remote add upstream https://github.com/kege/PDF-Extract-Kit.git # 4. 创建特性分支（feature branch），命名格式：feat/功能名 或 fix/问题描述 git checkout -b feat/table-output-format分支命名建议： -feat/xxx：新增功能 -fix/xxx：修复 Bug -doc/xxx：文档改进 -refactor/xxx：代码重构 -perf/xxx：性能优化
2.2 功能开发与本地测试
在新分支上进行修改时，请确保： - 遵循项目现有代码风格（Python PEP8 + 注释规范） - 新增功能需包含基本单元测试或集成测试说明 - 修改涉及用户界面时，应附带截图验证效果 - 不引入第三方依赖除非必要，并在 PR 中说明理由
示例：添加 Markdown 表格导出选项
# webui/components/table_parsing.py def parse_table_to_markdown(cells): """将表格单元格转换为 Markdown 格式""" if not cells: return "" header = "| " + " | ".join(cells[0]) + " |" separator = "|" + "|".join(["---"] * len(cells[0])) + "|" body = "\n".join([ "| " + " | ".join(row) + " |" for row in cells[1:] ]) return "\n".join([header, separator, body])2.3 提交 Commit 规范
每次提交请使用清晰、语义化的 commit message，推荐采用 Conventional Commits 格式：
git add . git commit -m "feat(table): add markdown export option" git push origin feat/table-output-format常用前缀说明： -feat: 新增功能 -fix: 修复缺陷 -docs: 文档变更 -style: 代码格式调整（不影响逻辑） -refactor: 重构代码 -test: 增加测试 -chore: 构建过程或辅助工具变动
3. 创建高质量 Pull Request
3.1 PR 创建步骤
- 访问你 Fork 的 GitHub 仓库页面
- 切换到你刚刚推送的特性分支
- 点击 “Compare & pull request”
- 填写 PR 模板内容（见下文）
3.2 PR 描述模板（必须填写）
为帮助维护者快速理解你的更改，请按如下模板完整填写 PR 描述：
## 📝 PR 概述 简要说明本次提交的目的和解决的问题。例如： > 本次 PR 为表格解析模块增加了 Markdown 输出格式支持，提升在笔记类场景下的可用性。 ## 🔧 修改内容 - [x] 在 `table_parsing.py` 中新增 `parse_table_to_markdown` 函数 - [x] 更新前端 UI 下拉菜单以包含 Markdown 选项 - [x] 添加输出示例至用户手册 ## 🖼️ 截图展示（如有）  ## ✅ 自查清单 - [x] 代码符合 PEP8 规范 - [x] 已进行本地功能测试 - [x] 不破坏原有功能 - [x] 提交信息清晰规范 - [x] 分支从最新主干同步过3.3 PR 审核流程说明
| 阶段 | 说明 |
|---|---|
| 待审核 | 维护者将在 3-5 个工作日内响应 |
| 请求修改 | 根据反馈调整代码后重新提交 |
| 合并准备 | 通过审查，等待合并 |
| 已合并 | 贡献正式纳入主干 |
💬提示：保持对 PR 页面的关注，及时回复评论或补充信息可加快审核速度。
4. 最佳实践与避坑指南
4.1 如何避免冲突与重复工作
- 提 PR 前先查 Issue 和 PR 列表：确认你要实现的功能是否已被提出或正在开发。
- 定期同步主干更新：
# 获取上游最新代码 git fetch upstream git rebase upstream/main # 推送更新后的分支 git push --force-with-lease- 小步快跑，分拆大功能：不要一次性提交大量改动。建议将复杂功能拆分为多个独立 PR，如：
feat: add table structure detectionfeat: implement html exportfeat: add markdown export
4.2 常见拒绝原因分析
| 问题类型 | 具体表现 | 正确做法 |
|---|---|---|
| 缺少描述 | 只写“update file” | 使用标准 PR 模板详细说明 |
| 引入冲突 | 修改了非相关文件 | 专注单一功能点 |
| 无测试验证 | 功能无法复现 | 提供运行截图或测试方法 |
| 代码混乱 | 缺少注释、变量命名随意 | 遵循项目编码规范 |
| 依赖膨胀 | 引入不必要的库 | 优先使用已有组件 |
4.3 文档与用户体验优化建议
如果你的 PR 涉及用户可见变更，请同步更新文档：
- 修改
README.md或用户使用手册.md - 更新参数说明表格
- 补充使用示例或快捷键说明
- 若增加新功能，建议在「常见使用场景」中添加对应案例
5. 总结
贡献开源项目不仅是代码提交，更是一次技术沟通与协作训练。通过遵守 PDF-Extract-Kit 的 PR 提交流程，你可以： - ✅ 提高代码被合并的概率 - ✅ 减少来回修改的时间成本 - ✅ 建立良好的开发者声誉 - ✅ 推动项目向更实用方向演进
我们欢迎每一位热爱文档智能处理的技术爱好者加入！无论是修复一个小 typo，还是实现一个全新模块，每一份用心的贡献都值得尊重。
最后再次强调：请务必使用特性分支提交 PR，填写完整描述，并附上必要的截图或测试说明。
💡获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。