Skip to content

docs: add CONTRIBUTING.md with verification loop, link from CLAUDE.md - #5449

Open
johnking0099 wants to merge 1 commit into
nextfrom
docs/contributing-and-verification-loop
Open

johnking0099 wants to merge 1 commit into
nextfrom
docs/contributing-and-verification-loop

Conversation

@johnking0099

Copy link
Copy Markdown
Member

动机

为面向开发者的贡献流程建立单一事实源(Refs MINERU-6):

  • 仓库此前没有 CONTRIBUTING.md,验证命令散落在对话与 CLAUDE.md 的编码规范中,人类贡献者与编码 agent 没有可直接复制的验证循环。
  • CLAUDE.md 是编码规范的事实源,但不应承担工作流命令的维护职责。

方案

  1. 新增 CONTRIBUTING.md(仓库根目录,面向人类贡献者与编码 agent 双读者):
    • 开发环境:不重复展开,引用 CLAUDE.md,仅补充 [test] / [torch] extras 的适用场景。
    • 验证循环(核心增量):ruff format/check 的确切命令与"改动零新增违规"门槛、pytest 单文件子集与全量的可复制命令(含 -o addopts="" 关闭默认 coverage 的说明)、解析质量改动的最小人工验证(mineru parse 逐 tier + mineru-kit models)、人工检查点。
    • PR 流程:分支命名、Conventional Commits、Refs #n 约定(引用 CLAUDE.md,无 fixes #n)、PR 描述三要素(动机/方案/验证证据)。
    • ADR 工作流:何时新增 docs/next/decisions/ ADR、四位递增编号规则、与专题文档的分工。
  2. CLAUDE.md 增量:在「GitHub Issue / PR 处理规范」前加「验证循环」小节,只指向 CONTRIBUTING.md,不复制命令。

验证证据

本 PR 为纯文档改动,未触碰任何代码。为确保文档中的命令真实可跑,在干净 checkout(next HEAD 317428b)上实测了全部命令(Python 3.13 + uv pip install -e ".[test]" + ruff 0.16.5):

  • ruff format --check mineru tests / ruff check mineru tests:实测发现 next HEAD 全仓有大量历史违规(ANN 系列为主,约 3180 条)。因此 CONTRIBUTING.md 将 lint 门槛定为"自己的改动零新增违规",并给出用 git diff --name-only 圈定文件的命令,而非声称全仓 check 可作合并门槛。
  • pytest tests/unittest/test_errors.py -q -o addopts="":7 passed。
  • 全量 pytest tests/unittest -q -o addopts=""(无 torch extra):约 5 分 40 秒,3649 passed / 37 failed / 11 skipped。失败均为既有问题,已如实写入 CONTRIBUTING.md 的"已知基线"小节:
    • test_mfr_latex_utils.pytest_pp_doclayoutv2_postprocess.py 收集失败(缺 torch);test_render_html_table.py 收集失败(依赖未在任何 extras 中声明的 markdown 包)。
    • tests/unittest/test_kit_commands.py 整体失败:mineru/cli_old/api_request.py:8 import 的 mineru.utils.backend_options 模块已不存在(85021ae5 重构后遗留)。
    • 其余失败集中在 tier preflight / model runtime 依赖检查用例,根因为缺 torch extra。
  • 文档中的 CLI 命令(mineru parse --tiermineru-kit models)已对照 mineru/cli/commands/parse.pymineru/kit/main.py 核实。

另备注两处与本 PR 无关、留待后续处理的发现:CLAUDE.md「开发环境」写的 uv pip install -e ".[core]"core extra 在 pyproject.toml 中并不存在(命令可执行但会落在基础依赖上);上述测试收集/既有失败清单已同步写入 CONTRIBUTING.md,避免后续贡献者误判为自己的改动引入。

留待后续(不在本 PR 范围)

docs/next 各篇文档的 状态: DraftImplemented 更新依赖 MINERU-5 的文档-代码漂移审计结论,审计落地后另行提交(存在漂移的文档一律不动)。

Co-authored-by: multica-agent <github@multica.ai>
@github-actions

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


Luban seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant