| name | rapid-contributing-guide |
| description | Creates or optimizes contributing/贡献指南 docs for RapidAI-style projects. Use when writing or updating docs/contributing.md to match the structure and conventions of RapidOCRDocs contributing guide (前置要求、一至八步骤、约定式提交、流程小结). |
Rapid 风格贡献指南文档
在为本仓库或同类 Rapid 项目编写、优化 docs/contributing.md 时，按以下结构与约定执行。
文档结构（必须保留）
- 前置要求：Python 版本、Git、GitHub 账号
- 一、克隆源码：主仓库 clone，可选说明网络受限时先 Fork
- 二、配置环境：虚拟环境（venv/conda）+
pip install -r requirements.txt、pytest、pip install -e .，可选推理依赖文档链接
- 三、安装 pre-commit：在仓库根目录执行
pre-commit install，说明提交前自动检查及 pre-commit run --all-files
- 四、运行单元测试：
pytest tests/ -v（及单文件、覆盖率示例），强调“确认基线通过再改”
- 五、复现问题 / 增加新功能：含“反馈问题与建议”（Bug/Feature/文档）及“复现 Bug”“增加新功能”子步骤
- 六、编写对应单元测试：测试目录、命名
test_*.py、资源目录（如 tests/test_files/）、测试原则 + 一段适配当前项目的 pytest 示例代码
- 七、运行所有单元测试：再次全量
pytest tests/ -v，提醒跳过用例的注意点
- 八、准备提交：8.1 Fork、8.2 推送到个人 Fork（remote、分支、commit、push）、8.3 提 PR
- 流程小结：用表格列出步骤 1～10 的简短说明
- 其他说明：代码风格（black/autoflake、pre-commit）、文档链接、Issues 链接；可选“文档本地预览”（如 MkDocs）
项目适配（替换占位）
- 仓库名与链接：全文替换为当前项目（如
RapidAI/RapidLayout、仓库 URL、文档站 URL、Issues URL）
- 目录结构：
- 若项目有
python/ 子目录：保留“进入 python 目录”、在 python/ 下跑 pytest、git add python/、commit 范围可写 fix(python):
- 若项目无
python/ 子目录：在仓库根目录克隆、安装、跑测；git add .；commit 类型示例用 fix:、feat:（可不带范围）
- 包名与测试：所有
rapidocr/rapid_layout 等包名、tests/ 路径、示例中的 engine 类名（如 RapidOCR/RapidLayout）按当前项目替换
- 文档站安装/使用链接：替换为当前项目的安装页、使用页
约定式提交（必须包含）
在「8.2 将代码提交到个人 Fork」下保留 Conventional Commits 说明与下表：
| 类型 | 说明 |
|---|
feat | 新功能 |
fix | Bug 修复 |
docs | 文档变更 |
style | 代码格式（不影响逻辑） |
refactor | 重构 |
test | 测试相关 |
chore | 构建/工具等 |
格式：<类型>[可选范围]: <简短描述>，并给 1～2 个示例。
PR 说明要点（必须包含）
在 8.3 中明确：base 为 RapidAI/当前仓库、base 分支 main；head 为贡献者 fork 与分支；说明中建议包含：对应 Issue（Fixes #123）、修改原因与改动、验证方式（如“在 xx 目录执行 pytest tests/ -v 通过”）。
可选内容
- 与 GitHub 同步提示：若主仓库有 CONTRIBUTING 文件且以主仓库为准，可在文首加 MkDocs
!!! tip 框，说明“文档站与主仓库同步，以 GitHub 为准”
- 文档本地预览：若项目用 MkDocs，在「其他说明」前增加“文档本地预览”小节，写
mkdocs serve 及访问地址
写作注意
- 所有代码块需可复制即用，路径、包名、仓库名已替换为当前项目
- 流程小结表格与正文一～八、八的 8.1～8.3 一一对应，无遗漏
- 语气保持简洁、一致，结尾可保留“再次感谢你的贡献！”
