MMagic 社区贡献实战指南：从 Fork 到 Pull Request 的完整协作流程与工程规范-平芜编程栈

媒体生成
计算机视觉
深度学习
人工智能
大模型

【免费下载链接】mmagic

OpenMMLab Multimodal Advanced, Generative, and Intelligent Creation Toolbox. Unlock the magic 🪄: Generative-AI (AIGC), easy-to-use APIs, awsome model zoo, diffusion models, for text-to-image generation, image/video restoration/enhancement, etc.

项目地址：https://gitcode.com/gh_mirrors/mm/mmagic

点击查看免费下载

MMagic（Multimodal Advanced, Generative, and Intelligent Creation Toolbox）是 OpenMMLab 旗下的多模态生成式 AI 工具箱，覆盖文本生成图像、图像/视频修复增强、图像补全、抠图等众多 AIGC 应用场景。本文以 MMagic 官方社区贡献指南为主线，系统讲解从 Fork 仓库、配置 pre-commit、提交单元测试到最终发起 Pull Request 的完整协作闭环，并结合仓库内的.pre-commit-config.yaml、setup.cfg、CI 工作流与tests/目录结构，为你提供一套可直接落地的开源贡献工程实践。读完本文，你将掌握 MMagic 的代码风格基线、测试与文档规范，以及一条不会踩坑的 PR 提交流程。

一、MMagic 社区与贡献方式总览

MMagic 社区致力于构建多模态高级生成与智能创作工具箱。正如 docs/en/index.rst 所描述的，该项目基于 PyTorch，支持无条件/条件 GAN、内部学习、扩散模型等基础生成模型，并覆盖 Text-to-Image、图像超分、视频超分、视频插帧、图像补全、图像抠图、图像修复、图像上色等丰富应用。

社区欢迎所有类型的贡献，包括但不限于以下三类：

修复 Bug：代码或文档中的笔误可以直接提交 Pull Request 修正。若改动涉及较深层的实现问题，建议先创建 Issue 描述报错信息与触发方式，与开发者讨论确定合理方案后再提交 PR，并补充对应的单元测试。
新特性或增强：涉及较大改动的特性应先创建 Issue 与开发者讨论设计，实现新特性/增强后提交 PR，并附带对应单元测试。
文档：文档修正可直接提交 PR；若要新增一篇文档，应先创建 Issue 确认其合理性，避免文档体系的无序膨胀。

二、Pull Request 完整工作流（七步走）

如果你对 Pull Request 尚不熟悉，不必担心，下面按官方指南的七个步骤逐步拆解，每一步都对应真实的仓库配置作为验证依据。

1. Fork 并克隆仓库

首次提交 PR 时，需要先在 GitHub 页面右上角点击Fork按钮，将 OpenMMLab 的仓库复制到自己的账号下。随后将 fork 得到的仓库克隆到本地：

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

克隆完成后，将官方仓库添加为 upstream 远端：

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

用git remote -v验证是否添加成功，正常应看到四条记录：

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

理解 origin 与 upstream 的分工是后续协作的关键：git clone默认创建指向所克隆仓库的origin；upstream是手动添加、指向目标官方仓库的远端，命名可自定义。日常开发将代码推送到origin；当推送的代码与官方最新代码冲突时，从upstream拉取最新代码解决冲突，再重新推送到origin，已提交的 Pull Request 会自动更新。

2. 配置 pre-commit

pre-commit 是 OpenMMLab 系列仓库统一采用的代码风格闸门，确保提交的代码风格与社区基线一致。注意：以下命令必须在 mmagic 目录下执行：

pip install -U pre-commit pre-commit install

执行pre-commit run --all-files可验证配置是否生效，并安装.pre-commit-config.yaml中定义的全部钩子：

pre-commit run --all-files

仓库根目录的 .pre-commit-config.yaml 是这套钩子体系的真实清单，从中可以看到 MMagic 实际启用的检查与格式化工具（含各工具版本）：

flake8（rev 4.0.1）：围绕多种 linter 的包装器，执行代码风格与基础错误检查；
isort（5.12.1）：自动排序 import 语句；
yapf（v0.30.0）：Google 出品的 Python 格式化器；
pre-commit/pre-commit-hooks（v3.1.0）：包含 trailing-whitespace、check-yaml、end-of-file-fixer、requirements-txt-fixer、double-quote-string-fixer、check-merge-conflict、fix-encoding-pragma（--remove）、mixed-line-ending（--fix=lf）等通用钩子；
codespell（v2.1.0）：修正文本中的常见拼写错误（跳过*.ipynb并忽略特定词表）；
mdformat（0.7.9）：Markdown 格式化器，配合--number、--table-width 200以及 mdformat-openmmlab、mdformat_frontmatter、linkify-it-py 等插件；
docformatter（v1.3.1）：docstring 格式化（--in-place --wrap-descriptions 79）；
本地钩子 update-model-index：当configs/下的.md文件变更时，自动运行.dev_scripts/update_model_index.py收集模型信息并更新model-index.yml；
open-mmlab/pre-commit-hooks（v0.4.0）：check-algo-readme、check-copyright（作用于demo、mmagic、tests、tools目录）、remove-improper-eol-in-cn-docs；
本地钩子 update-model-zoo：通过docs/en/.dev_scripts/update_model_zoo.py维护模型动物园清单。

如果代码不符合风格规范，pre-commit 会给出警告并自动修复部分错误；安装过程若被中断，可重复执行pre-commit run ...继续安装。若确需临时绕过钩子提交（仅限临时提交），可使用：

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

对于受网络问题影响、无法从默认源下载钩子的中文用户，官方指南提供了 Gitee 镜像配置：

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

3. 创建开发分支

配置好 pre-commit 后，应基于 main 分支创建开发分支，建议分支命名为username/pr_name：

git checkout -b yhc/refactor_contributing_doc

后续开发过程中，如果本地 main 分支落后于 upstream 的 main，需要先同步再创建分支：

git pull upstream main

4. 提交代码并通过单元测试

提交前需满足两个硬性要求：

类型检查：MMagic 引入 mypy 做静态类型检查以提升代码健壮性，因此新代码需要添加 Type Hints 并通过 mypy 检查（不熟悉 Type Hints 可参考 Python 官方 typing 文档）。

单元测试：提交的代码必须通过单元测试，官方给出的命令为：

# 运行全部单元测试 pytest tests # 运行指定测试模块 pytest tests/test_engine/test_runner/test_multi_loops.py

从仓库结构看，tests/ 目录按被测对象划分为test_apis、test_datasets、test_engine（含test_hooks、test_optimizers、test_runner、test_schedulers）、test_evaluation（含test_functional、test_metrics）、test_models（含test_archs、test_base_models、test_data_preprocessors、test_diffusion_schedulers、test_editors、test_losses、test_utils）、test_structures、test_utils、test_visualization，与 setup.cfg 中testpaths = tests/的 pytest 配置一一对应。例如 runner 相关测试实际位于 tests/test_engine/test_runner/，包含test_log_processor.py、test_loop_utils.py、test_multi_loops.py等文件，可用上述命令单独运行验证。

若单元测试因缺少依赖而失败，可参照下文"单元测试与覆盖率"一节安装依赖。

若修改/新增了文档，还需按下文"文档渲染"一节的指引检查渲染结果。

5. 推送代码到远端

通过单元测试与 pre-commit 检查后，即可将本地提交推送到远端。通过-u选项将本地分支与远端分支关联：

git push -u origin {branch_name}

此后可直接使用git push推送，无需再指定分支与远端。

6. 创建 Pull Request

（1）在 GitHub 的 Pull request 界面创建 PR。

（2）按规范撰写 PR 描述，使其他开发者能快速理解改动内容，具体规范见下文"PR 规范"一节。

（3）PR 描述与流程上还有三点注意事项：

(a) PR 描述应包含改动原因、改动内容与改动影响，并关联相关 Issue；
(b) 若是首次贡献，请签署 CLA；
(c) 检查 PR 是否通过 CI。

MMagic 会对提交的 PR 在不同平台（Linux、Windows、Mac）、不同 Python、PyTorch、CUDA 版本组合下运行单元测试以验证正确性。点击 CI 面板中的Details可查看具体测试信息并据此修改代码。仓库中 .github/workflows/pr_stage_test.yml 展示了这套机制的实现：PR 触发时在ubuntu-22.04上构建 CPU 环境，安装指定版本 PyTorch/torchvision（如 2.0.1/0.15.2）、MMEngine、MMCV，安装requirements/tests.txt依赖后执行pip install -e .，再以coverage run --branch --source mmagic -m pytest tests/运行全量单元测试并生成覆盖率报告上传至 Codecov；工作流同时声明了对README.md、docs/**、configs/**等路径的忽略，避免纯文档/配置改动触发全量测试。

（4）PR 通过 CI 后，等待其他开发者 review。根据评审意见修改代码，重复步骤 4–5（提交测试、推送远端），直到所有 reviewer 批准，随后 PR 会被尽快合入。

7. 解决冲突

若本地分支与 upstream 最新 main 分支冲突，有两种解决方式：

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

或：

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

官方建议：擅长处理冲突时优先使用rebase，可以保持提交日志整洁；对rebase不熟悉时使用merge解决冲突。

三、配套开发指导（Guidance）

单元测试与覆盖率

提交的代码不应降低单元测试覆盖率，官方提供如下检查命令：

python -m coverage run -m pytest /path/to/test_file python -m coverage html # 在 htmlcov/index.html 中查看覆盖率报告

这与 CI 中coverage run --branch --source mmagic -m pytest tests/的做法同源，帮助你在本地提前复现 CI 的覆盖率检查结果。

文档渲染

若修改/新增了文档，需要检查渲染结果。先安装文档依赖，再执行 Sphinx 构建：

pip install -r requirements/docs.txt cd docs/zh_cn/ # 或 cd docs/en make html # 在 ./docs/zh_cn/_build/html/index.html 中查看渲染结果

requirements/docs.txt 锁定了文档构建依赖版本（如sphinx==4.5.0、docutils==0.16.0、myst_parser、pytorch_sphinx_theme、sphinx-copybutton、sphinx-notfound-page、sphinx-tabs、sphinx_markdown_tables、sphinx-autoapi等）；docs/en/conf.py 中启用了intersphinx、napoleon、viewcode、autosectionlabel、myst_parser等扩展，并将../../mmagic设为 autoapi 的扫描目录，同时定义BUILDDIR = _build（见 docs/en/Makefile），与上述命令中的输出路径完全对应。

四、代码风格规范

Python 风格

MMagic 采用PEP8作为首选代码风格，并使用以下工具进行 lint 与格式化：

flake8：多种 linter 的包装器；
isort：排序 import 的 Python 工具；
yapf：Python 格式化器；
codespell：修正文本常见拼写错误；
mdformat：强制 Markdown 风格一致的格式化器；
docformatter：docstring 格式化器。

yapf 与 isort 的风格配置可在仓库根目录的 setup.cfg 中找到，其关键配置包括：[yapf]段基于pep8风格、blank_line_before_nested_class_or_def = true等；[isort]段设置line_length = 79、known_first_party = mmagic，并预置了PIL, cv2, lmdb, mmcv, numpy, onnx, onnxruntime, packaging, pymatting, pytest, pytorch_sphinx_theme, requests, scipy, titlecase, torch, torchvision, ts等第三方库分组；[flake8]段因 yapf 冲突忽略 E251，并对*/__init__.py的 F401、mmagic/configs/*的 F401/F403/F405/E501 做了 per-file 豁免。

pre-commit 钩子在每次提交时自动执行flake8、yapf、isort检查与格式化，并处理 trailing whitespaces、markdown 文件、文件末尾空行（end-of-file）、双引号字符串、python-encoding-pragma、混合行尾（mixed-line-ending），同时自动排序requirements.txt。钩子配置即上文展示的 .pre-commit-config.yaml。

C++ 和 CUDA

C++/CUDA 代码遵循Google C++ Style Guide。

五、PR 规范（PR Specs）

官方对 PR 本身提出了五条硬性规范：

使用 pre-commit 钩子，规避代码风格问题；
一个短周期分支只对应一个 PR，保持分支与改动一一对应；
一个 PR 完成一个具体改动，避免过大的 PR。官方给出的粒度示例：
- Bad：Support Faster R-CNN（范围过大）
- Acceptable：Add a box head to Faster R-CNN（可接受的模块级改动）
- Good：Add a parameter to box head to support custom conv-layer number（理想的参数级改动）
提供清晰且有意义的提交信息（commit message）；
提供清晰且有意义的 PR 描述：
- 标题应明确任务名称，通用格式为[Prefix] Short description of the PR (Suffix)；
- Prefix 约定：新特性[Feature]、修 Bug[Fix]、文档相关[Docs]、开发中[WIP]（WIP 暂不进入评审）；
- 简短描述中说明主要改动、结果及对其他模块的影响；
- 关联相关 Issue 与 Pull Request 至同一个 milestone。

六、CI 流水线对贡献者的实际意义

除了 .github/workflows/pr_stage_test.yml 的多平台/多版本单元测试矩阵，仓库还提供了 .github/workflows/lint.yml 作为代码质量闸门：该工作流在 push 与 pull_request 时触发，安装 pre-commit 后执行pre-commit run --all-files做全量风格检查，并通过 interrogate 校验 docstring 覆盖率（--fail-under 90）。这意味着贡献者的 PR 不仅要通过单元测试，还要在提交前就通过完整的 pre-commit 检查链，否则 CI 会直接亮红灯。

综合来看，MMagic 的贡献流程是一个"本地 pre-commit + 单元测试 → 远端 CI 多平台矩阵 → reviewer 评审"的三层质量体系。只要严格遵循本文梳理的七步工作流、代码风格规范与 PR 规范，并善用pytest tests、coverage、make html等本地验证手段，就能以最低的沟通成本提交高质量 PR，顺利融入 MMagic 社区的开源协作。