MMCV 贡献指南：从 Fork 仓库到合入 PR 的完整开发工作流

• 人工智能
• 计算机视觉
• 深度学习

本指南面向希望为 OpenMMLab 计算机视觉基础库 MMCV 贡献代码的开发者，完整梳理了从提交 issue、修复错误或新增组件，到通过 pre-commit 检查、本地单元测试与 CI，最终合入拉取请求（PR）的全流程。阅读并实践本文后，你将能够独立完成一次规范的开源贡献：正确复刻仓库、配置代码风格钩子、编写带类型注解的代码与单元测试，并提交一份符合 MMCV 维护规范的 PR。

参与贡献的三种方式与前置流程

MMCV 欢迎任何类型的贡献，官方将贡献分为三类，每一类都给出了对应的推荐流程：

修复错误

1. 如果提交的代码改动较大，建议先提交 issue，并正确描述 issue 的现象、原因和复现方式，讨论后确认修复方案；
2. 修复错误并补充相应的单元测试，提交拉取请求。

新增功能或组件

1. 如果新功能或模块涉及较大的代码改动，建议先提交 issue，确认功能的必要性；
2. 实现新增功能并添加单元测试，提交拉取请求。

文档补充

• 修复文档可以直接提交拉取请求，无需先开 issue；
• 添加文档或将文档翻译成其他语言，则建议先提交 issue 确认必要性，再添加文档并提交拉取请求。

从仓库现状看，中文社区文档目录 内的 pr.md 已注明"本文档的内容已迁移到贡献指南"，说明贡献指南是社区协作流程的唯一权威入口；而仓库根目录还维护着一份与本文内容一致的中英文贡献指南（CONTRIBUTING_zh-CN.md 与 CONTRIBUTING.md），供以仓库根目录为入口的贡献者阅读。

拉取请求工作流：从零开始提交第一个 PR

如果你对拉取请求的协作模式还不熟悉，下面按 7 个步骤完整演示一次 PR 的诞生过程。

第 1 步：复刻仓库

第一次提交 PR 时，需要先复刻 OpenMMLab 原代码库：点击仓库页面右上角的Fork按钮，复刻后的代码库会出现在你的个人主页下。

将复刻得到的仓库克隆到本地（{username}替换为你的 GitHub 用户名）：

git clone git@github.com:{username}/mmcv.git

然后添加原代码库为上游（upstream）代码库：

git remote add upstream git@github.com:open-mmlab/mmcv

检查 remote 是否添加成功，在终端输入git remote -v，应看到类似输出：

origin git@github.com:{username}/mmcv.git (fetch) origin git@github.com:{username}/mmcv.git (push) upstream git@github.com:open-mmlab/mmcv (fetch) upstream git@github.com:open-mmlab/mmcv (push)

这里需要理解origin与upstream的分工：git clone时默认创建的origin指向你 fork 下来的远程仓库，而upstream是你手动添加的、指向原始代码库的远程地址（名字可以自定义，例如open-mmlab）。日常开发中我们通常向origin推送代码，然后向upstream提交 PR；如果提交的代码与最新代码冲突，再从upstream拉取最新代码、在本地分支解决冲突后重新推送到origin。

第 2 步：配置 pre-commit

MMCV 在本地开发环境使用 pre-commit 来统一代码风格。提交代码前，需要先在 MMCV 目录下安装并激活钩子：

pip install -U pre-commit pre-commit install

随后检查配置是否成功，并安装 .pre-commit-config.yaml 中声明的全部钩子：

pre-commit run --all-files

针对中国用户，由于网络原因可能出现钩子安装失败的情况，仓库为此提供了国内镜像版本配置 .pre-commit-config-zh-cn.yaml（钩子来源替换为 Gitee 镜像），改用如下命令即可：

pre-commit install -c .pre-commit-config-zh-cn.yaml pre-commit run --all-files -c .pre-commit-config-zh-cn.yaml

如果安装过程被中断，可以重复执行pre-commit run ...继续安装。当提交的代码不符合风格规范时，pre-commit 会发出警告，并自动修复部分错误；如果想临时绕开检查提交一次代码，可以在git commit时加上--no-verify（但必须保证最终推送至远程仓库的代码能通过 pre-commit 检查）：

git commit -m "xxx" --no-verify

从仓库的 .pre-commit-config.yaml 可以看到，MMCV 的钩子链相当完整：validate_manifest、flake8、isort、yapf、trailing-whitespace、check-yaml、end-of-file-fixer、requirements-txt-fixer、double-quote-string-fixer、check-merge-conflict、fix-encoding-pragma、mixed-line-ending、codespell、mdformat、docformatter、pyupgrade、check-copyright（检查mmcv、tests目录的版权头，排除mmcv/ops）以及mypy（对tests与docs之外的文件做静态类型检查）。其中mdformat还加载了mdformat-openmmlab等附加依赖，确保 Markdown 文档的格式也遵循 OpenMMLab 约定。

第 3 步：创建开发分支

安装完 pre-commit 后，基于main分支创建开发分支，建议的分支命名规则为username/pr_name：

git checkout -b yhc/refactor_contributing_doc

在后续开发中，如果本地仓库的main分支落后于upstream的main分支，需要先拉取 upstream 的代码进行同步，再创建分支：

git pull upstream main

第 4 步：提交代码并在本地通过单元测试

补充类型注解。MMCV 引入了 mypy 做静态类型检查，以增加代码的鲁棒性，因此提交代码时需要补充 Type Hints（具体规则可参考仓库内 OpenMMLab 代码规范 中"类型注解"一节，以及 .pre-commit-config.yaml 中 mypy 钩子的配置）。

通过单元测试。提交的代码必须通过测试：

# 通过全量单元测试 pytest tests # 运行修改模块的单元测试 pytest tests/test_cnn/test_wrappers.py

原贡献指南以tests/test_runner/test_runner.py作为"运行修改模块测试"的示例；以当前仓库为准，tests 目录按模块组织为test_cnn/、test_image/、test_ops/、test_transforms/、test_utils/、test_video/等（例如 tests/test_video/test_reader.py），因此只需将命令中的路径替换为你所修改模块对应的测试文件即可。

如果你由于缺少依赖无法运行修改模块的单元测试，可参考下文 单元测试指引 安装所需依赖；如果修改或添加了文档，则参考 文档渲染指引 确认渲染正常。

第 5 步：推送代码到远程

代码通过单元测试和 pre-commit 检查后，将代码推送到远程仓库。如果是第一次推送，可在git push后加上-u参数以关联远程分支：

git push -u origin {branch_name}

这样后续就可以直接使用git push推送，无需再指定分支和远程仓库。

第 6 步：提交拉取请求（PR）

1. 在 GitHub 的 Pull request 界面创建拉取请求；
2. 根据指引修改 PR 描述，以便其他开发者理解你的修改（描述规范详见下文 拉取请求规范）。

提交 PR 时还需注意以下三点：

• (a) PR 描述应包含修改理由、修改内容以及修改后带来的影响，并关联相关 issue；
• (b) 首次为 OpenMMLab 做贡献需要签署 CLA；
• (c) 检查提交的 PR 是否通过 CI（集成测试）。

关于 CI，MMCV 会在不同平台（Linux、Windows、Mac），基于不同版本的 Python、PyTorch、CUDA 对提交的代码进行单元测试以保证正确性。仓库的 .github/workflows 目录下可以看到具体的流水线定义，例如 lint.yml（代码风格检查）、pr_stage_test.yml（PR 阶段测试）与 merge_stage_test.yml（合入前测试）。如果有任何一个任务没有通过，可点击 CI 结果中的Details查看具体测试信息，据此修改代码。

3. 如果 PR 通过了 CI，就可以等待其他开发者的 review，并根据 reviewer 的意见修改代码，重复第 4~5 步（本地测试、推送代码），直到 reviewer 同意合入；所有 reviewer 同意后，维护者会尽快将 PR 合并到主分支。

第 7 步：解决冲突

随着代码库不断更新，你的 PR 可能随时间与主分支产生冲突，解决方式有两种：

方式一（rebase）：

git fetch --all --prune git rebase upstream/main

方式二（merge）：

git fetch --all --prune git merge upstream/main

如果你非常善于处理冲突，推荐使用 rebase 方式，它能保证 commit log 的整洁；如果对 rebase 不熟悉，则使用 merge 方式即可。

贡献指引：单元测试与文档渲染

单元测试指引

如果你无法正常执行部分模块的单元测试（例如 mmcv/video 模块），很可能是当前环境缺少相应依赖，例如视频模块依赖libturbojpeg与ffmpeg：

# Linux sudo apt-get update -y sudo apt-get install -y libturbojpeg sudo apt-get install -y ffmpeg # Windows conda install ffmpeg

对应地，tests/test_video 目录下的test_reader.py、test_optflow.py、test_processing.py覆盖了视频读取、光流与处理逻辑，提交这些模块的改动前应确保相关依赖已安装并能跑通对应测试。

在提交修复代码错误或新增特性的 PR 时，应尽可能让单元测试覆盖所有提交的代码。计算单元测试覆盖率的方法如下：

python -m coverage run -m pytest /path/to/test_file python -m coverage html # check file in htmlcov/index.html

运行后在htmlcov/index.html中查看覆盖率报告。

文档渲染指引

在提交修复代码错误或新增特性的 PR 时，可能需要修改或新增模块的 docstring，需确认渲染后的文档样式正确。本地生成渲染后文档的方法如下：

pip install -r requirements/docs.txt cd docs/zh_cn/ # 或 cd docs/en make html # check file in ./docs/zh_cn/_build/html/index.html

requirements/docs.txt 中锁定了文档渲染所需的依赖，包括sphinx==4.0.2、myst-parser、markdown、sphinx-copybutton、docutils、OpenMMLab 的pytorch_sphinx_theme等，渲染完成后在docs/zh_cn/_build/html/index.html检查效果。注意，由于文档系统采用 reStructuredText 语法（docstring 中的:obj:、双反引号等标记会被 Sphinx 特殊解析），在提交前最好生成并预览一次，避免产生渲染错误。

代码风格规范

Python：PEP 8 与格式化工具链

PEP 8 是 OpenMMLab 算法库首选的 Python 代码规范，MMCV 使用以下工具检查和格式化代码：

• flake8：Python 官方发布的代码规范检查工具，是多个检查工具的封装；
• isort：自动调整模块导入顺序的工具；
• yapf：Google 发布的代码格式化工具；
• codespell：检查单词拼写是否有误；
• mdformat：检查 Markdown 文件的工具；
• docformatter：格式化 docstring 的工具。

yapf 和 isort 的配置可在 setup.cfg 中找到，例如 yapf 基于pep8风格并开启split_before_expression_after_opening_paren，isort 限定line_length = 79、将mmcv设为 first-party 模块、按 OpenMMLab 惯例排布第三方库顺序（addict, cv2, matplotlib, numpy, onnx, packaging, pytest, torch, torchvision, yaml, yapf等）。此外 setup.cfg 中还包含 codespell 的ignore-words-list配置。

通过配置 pre-commit hook，可以在提交代码时自动检查和格式化 flake8、yapf、isort、trailing whitespaces、markdown files，并修复 end-of-files、double-quoted-strings、python-encoding-pragma、mixed-line-ending 等问题，还能自动调整requirements.txt中的包顺序。pre-commit 钩子的完整配置见 .pre-commit-config.yaml，其安装使用方式见上文"配置 pre-commit"一节。更具体的代码规范（命名规范、docstring 规范、注释规范、类型注解规范及 mypy 使用示例）请参考 OpenMMLab 代码规范。

C++ 与 CUDA

MMCV 的算子大量涉及 C++ 与 CUDA 实现（见 mmcv/ops 下按pytorch/cuda、pytorch/cpu等目录组织的算子源码），其代码规范遵从 Google C++ Style Guide。当前仓库的 .pre-commit-config.yaml 中保留了一份被注释掉的clang-format本地钩子配置（针对.c/.cc/.cpp/.cu/.h/.hpp/.cuh等文件、使用-style=google），可作为 C++/CUDA 代码风格检查的参考实现思路。

拉取请求规范

为了让 PR 更容易被 review 并合入，MMCV 对 PR 本身提出了六条硬性规范：

1. 使用 pre-commit hook，尽量减少代码风格相关问题；
2. 一个 PR 对应一个短期分支；
3. 粒度要细，一个 PR 只做一件事情，避免超大 PR。示例：
   • Bad：实现 Faster R-CNN
   • Acceptable：给 Faster R-CNN 添加一个 box head
   • Good：给 box head 增加一个参数来支持自定义的 conv 层数
4. 每次 Commit 提供清晰且有意义的 commit 信息；
5. 提供清晰且有意义的 PR 描述：
   • 标题写明白任务名称，一般格式：[Prefix] Short description of the pull request (Suffix)；
   • prefix 约定：新增功能[Feature]、修 bug[Fix]、文档相关[Docs]、开发中[WIP]（WIP 状态暂时不会被 review）；
   • 描述里介绍 PR 的主要修改内容、结果，以及对其他部分的影响，可参考 PR 模板；
   • 关联相关的 issue 和其他 PR；
6. 如果引入了其他三方库，或借鉴了三方库的代码，请确认它们的许可证与 MMCV 兼容，并在借鉴的代码上补充This code is inspired from http://...形式的来源说明。

仓库在 .github/pull_request_template.md 提供了标准 PR 模板，包含 Motivation（动机）、Modification（修改内容）、BC-breaking（是否破坏下游向后兼容性）、Use cases（新特性使用场景）以及 PR 前后 Checklist（是否遵循 CONTRIBUTING 工作流、是否通过 lint、bug 是否覆盖单元测试、文档是否同步更新、是否已签署 CLA、是否需要在下游 MMDet/MMCls 等项目上验证影响），提交 PR 时按模板填写即可。

仓库内相关资源一览

• .pre-commit-config.yaml：pre-commit 钩子完整配置（flake8、isort、yapf、codespell、mdformat、mypy、check-copyright 等）；
• .pre-commit-config-zh-cn.yaml：面向中国用户的 Gitee 镜像版配置；
• setup.cfg：yapf、isort、codespell 风格配置；
• docs/zh_cn/community/code_style.md：OpenMMLab 代码规范详解（命名、docstring、注释、类型注解）；
• .github/pull_request_template.md：标准 PR 描述模板；
• .github/workflows/lint.yml 与 .github/workflows/pr_stage_test.yml：CI lint 与 PR 阶段测试流水线；
• requirements/docs.txt：文档渲染依赖清单；
• CONTRIBUTING_zh-CN.md 与 CONTRIBUTING.md：仓库根目录维护的贡献指南（内容与本指南一致）；
• docs/zh_cn/community/pr.md：旧版 PR 文档，内容已迁移至本贡献指南。

• 人工智能
• 计算机视觉
• 深度学习