MMAction2 贡献指南：从 Fork 到 PR 的完整代码规范与提交流程-育师

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

【免费下载链接】mmaction2

OpenMMLab's Next Generation Video Understanding Toolbox and Benchmark

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

导读

本文基于 docs/en/get_started/contribution_guide.md 整理，系统讲解如何向 MMAction2 视频理解工具箱贡献代码：从 Fork 上游仓库、创建功能分支、提交改动到最终创建 Pull Request 的完整工作流，并深入剖析仓库内置的 Python / C++ 代码风格规范、yapf/isort/flake8 等工具链配置，以及基于 pre-commit 的提交前自动检查机制。读完本文，你将能够按照官方规范完成一次合规的代码贡献，并掌握通过projects/目录以更低门槛向 MMAction2 提交独立视频理解算法项目的完整套路。

一、可以贡献什么

MMAction2 欢迎各类形式的贡献，官方文档明确列出以下四类（见 contribution_guide.md）：

修复（Fixes）：包括拼写错误、文档笔误、代码缺陷等；
新特性与组件（New features and components）：为工具箱增加新的模型、模块或能力；
文档（Documentation）：新增文档，或将其翻译为其他语言；
新项目（Add new project，推荐）：围绕视频理解算法贡献相对独立、约束较少的项目，详情参见 projectzoo 说明与 projects/README.md。

其中，“新项目”是被官方明确推荐的贡献形式。projects/README.md 指出，该目录对代码标准的要求不像核心包（mmaction/）那样严格，社区开发者可以更轻松高效地在 MMAction2 中实现自己的算法，并且官方提供了 example_project 作为可复制的范例模板。

二、贡献流程：从 Fork 到 PR 的标准工作流

官方文档给出了最简的四步工作流，全部 PR 都应当遵循这一流程：

Fork 并拉取最新的 mmaction2：先在上游仓库页面点击 Fork 得到个人副本，再将其克隆到本地。例如：

git clone https://gitcode.com/gh_mirrors/mm/mmaction2 cd mmaction2 git remote add upstream https://gitcode.com/gh_mirrors/mm/mmaction2 git checkout main git pull upstream main

新建一个有意义的命名分支（不要直接在 main 分支上提交 PR）：分支名应当能清晰表达本次改动意图，例如fix-tsn-head-bug、add-vit-backbone；
```
git checkout -b your-feature-branch
```
提交你的改动：在分支上完成编码，并确保代码通过下文的 lint 与格式化检查后再提交（git commit）；
创建 Pull Request：将本地分支推送（git push origin your-feature-branch）后，在上游仓库发起 PR，等待评审。

文档还给出了两条重要提示（见 contribution_guide.md）：

如果你计划新增涉及大量改动的新特性，建议先开一个 issue 进行讨论，避免方向性返工；
如果你是某篇论文的作者，希望在 MMAction2 中收录自己的方法，可以主动联系维护团队，社区非常欢迎这类贡献。

三、Python 代码风格与工具链

3.1 总体原则：遵循 PEP 8

MMAction2 的 Python 代码采用 PEP 8 作为首选风格，并在此基础上使用以下工具进行 lint 与格式化（原文档工具清单）：

工具	定位
flake8	代码 linter，检查语法与风格问题
yapf	代码格式化器，统一代码排版
isort	自动整理 import 语句顺序
codespell	修复文本文件中的常见拼写错误
mdformat	Markdown 格式化器，强制 Markdown 文件风格一致
docformatter	docstring（文档字符串）格式化器

这些工具均已写入仓库的 requirements/tests.txt，与coverage、interrogate、parameterized、pytest、xdoctest等测试依赖放在一起，说明它们属于“开发测试环境”的标准组成部分。

3.2 yapf 与 isort 的仓库级配置

yapf 与 isort 的风格配置存放在仓库根目录的 setup.cfg 中，核心参数如下：

[yapf] based_on_style = pep8 # 以 PEP8 为基础风格 blank_line_before_nested_class_or_def = true split_before_expression_after_opening_paren = true split_penalty_import_names = 0 SPLIT_PENALTY_AFTER_OPENING_BRACKET = 800 [isort] line_length = 79 # 行宽 79，与 PEP8 一致 multi_line_output = 0 extra_standard_library = pkg_resources,setuptools known_first_party = mmaction # mmaction 视为第一方包 known_third_party = cv2,decord,einops,joblib,matplotlib,mmcv,numpy,pandas, pytest,pytorch_sphinx_theme,scipy,seaborn,titlecase,torch, webcolors no_lines_before = STDLIB,LOCALFOLDER default_section = THIRDPARTY [flake8] per-file-ignores = mmaction/configs/*:F401,F403,F405 # 对配置文件目录放宽未使用导入等告警

从源码结构看，这段配置对贡献者的实际意义在于：known_first_party = mmaction保证import mmaction...相关语句按第一方包处理，known_third_party白名单则避免了cv2、torch、mmcv等第三方库被 isort 误判；行宽 79 与 PEP 8 保持一致，是评审中最常见的硬性约束之一。

3.3 pre-commit：提交时自动执行检查

仓库使用 pre-commit）：

flake8：代码 lint；
isort：import 排序；
yapf：代码格式化；
trailing-whitespace / check-yaml / end-of-file-fixer：去除行尾空白、校验 YAML、保证文件末尾换行；
requirements-txt-fixer：自动排序requirements.txt；
double-quote-string-fixer：统一字符串引号；
check-merge-conflict：检测未解决的合并冲突标记；
fix-encoding-pragma（--remove）：移除# -*- coding: -*-旧式编码声明；
mixed-line-ending（--fix=lf）：统一为 LF 换行；
docformatter：以--in-place --wrap-descriptions 79格式化 docstring；
codespell：以--skip *.ipynb并忽略ECT,Gool,tread,gool,mot等误报词汇检查拼写；
mdformat：以--number --table-width 200并配合mdformat-openmmlab、mdformat_frontmatter、linkify-it-py插件格式化 Markdown；
check-algo-readme / check-copyright（来自 open-mmlab 官方 pre-commit 钩子）：检查算法 README 规范与mmaction、tests、demo、tools目录的文件版权头。

克隆仓库后，需要安装并初始化 pre-commit 钩子（官方文档命令）：

pip install -U pre-commit

然后在仓库根目录执行：

pre-commit install

此后每一次git commit都会自动强制执行上述 lint 与格式化检查，未通过检查的提交会被拦截，相关文件会被自动改写，需要重新git add后再提交。

官方文档特别强调：在创建 PR 之前，务必确保代码通过 lint 且已由 yapf 格式化（见 contribution_guide.md）。

四、C++ 与 CUDA 代码风格

对于仓库中可能涉及的 C++ 与 CUDA 扩展（例如自定义算子），官方文档明确要求遵循 Google C++ Style Guide。这意味着命名、缩进、注释、头文件组织等都需要按 Google 规范执行，与 Python 侧采用 PEP 8 形成互补，共同覆盖 MMAction2 前后端全部代码。

五、推荐路径：通过 projects/ 贡献新算法

如果你要贡献的是一个相对独立的视频理解算法（而非修改核心包），官方推荐走projects/目录，仓库中已内置完整可复制的范例 projects/example_project。从该范例的源码结构看，一个标准项目通常包含三部分：

projects/example_project/ ├── README.md # 项目说明（使用方式、结果、引用、checklist） ├── configs/ # 训练/测试配置文件 └── models/ # 模型实现与模块注册

5.1 模型注册：接入 mmaction 的组件体系

核心包的组件通过 registry 机制注册，projects/项目同样遵循这一约定。example_net.py 展示了标准写法：

from mmaction.models import ResNet from mmaction.registry import MODELS # Register your model to the `MODELS`. @MODELS.register_module() class ExampleNet(ResNet): """Implements an example backbone. Implement the backbone network just like a normal pytorch network. """ def __init__(self, **kwargs) -> None: print('#############################\n' '# Hello MMAction2! #\n' '#############################') super().__init__(**kwargs) def forward(self, x): """Defines the computation performed at every call.""" return super().forward(x)

关键点有二：一是通过@MODELS.register_module()将自定义网络注册进mmaction.registry.MODELS，使其可以被配置文件以type='ExampleNet'的方式实例化；二是每个主要类都应包含 docstring，说明其功能与参数（对应 checklist 中的 “Basic docstrings & proper citation” 要求）。配套的 models/init.py 只需导出该模块即可。

5.2 配置继承：最小化配置改动

配置文件展示了项目配置如何基于核心包配置做最小改动：

# Directly inherit the entire recipe you want to use. _base_ = 'mmaction::recognition/tsn/' \ 'tsn_imagenet-pretrained-r50_8xb32-1x1x3-100e_kinetics400-rgb.py' # This line is to import your own modules. custom_imports = dict(imports='models') # Modify the backbone to use your own backbone. _base_['model']['backbone'] = dict(type='ExampleNet', depth=50) # Modify the in_channels of classifier head to fit your backbone. _base_['model']['cls_head']['in_channels'] = 2048

其中_base_ = 'mmaction::...'直接继承核心包中现成的完整配方（这里以 TSN 的 R50 配置为基底）；custom_imports = dict(imports='models')让配置加载时自动导入projects/<name>/models目录下的自定义模块；随后只需把model.backbone替换为dict(type='ExampleNet', depth=50)，并按骨干网络输出通道（ResNet50 为 2048）调整分类头in_channels。这种“继承 + 覆盖”的写法使新算法几乎不用重写配置。

5.3 运行与结果验证

在 projects/example_project/README.md 中给出了标准的训练/测试命令模板，先执行export PYTHONPATH=\pwd`:$PYTHONPATH`（每次打开新 shell 后都要重新执行）让 Python 能找到项目代码，然后：

# 单卡训练 mim train mmaction configs/examplenet_r50-in1k-pre_8xb32-1x1x3-100e_kinetics400-rgb.py # 多卡训练（pytorch launcher） mim train mmaction configs/examplenet_r50-in1k-pre_8xb32-1x1x3-100e_kinetics400-rgb.py --launcher pytorch --gpus 8 # 测试（单卡） mim test mmaction configs/examplenet_r50-in1k-pre_8xb32-1x1x3-100e_kinetics400-rgb.py --checkpoint $CHECKPOINT

范例 README 还要求以表格形式给出结果（帧采样策略、分辨率、GPU 数、backbone、预训练、top1/top5 精度、测试协议、config/ckpt/log 链接），并附上论文引用格式（bibtex）。

六、测试与质量保障

虽然贡献指南正文聚焦于风格规范，但仓库的测试基础设施是 PR 评审的重要组成部分。测试依赖集中在 requirements/tests.txt：pytest作为测试框架，coverage统计覆盖率，interrogate检查 docstring 覆盖率，xdoctest支持在 docstring 中运行示例代码。

单元测试统一放在 tests/ 目录，与mmaction/包结构一一对应。以 tests/models/backbones/test_resnet.py 为例，它通过pytest.raises断言非法参数（如ResNet(20)的非法深度、num_stages=0、style='tensorflow'等）会被正确拦截，再构造 demo 输入验证各深度网络的输出特征形状（如 depth 50 输出torch.Size([1, 2048, 2, 2])），并检查norm_eval、frozen_stages、partial_bn等训练期行为。这类“非法参数 + 前向形状 + 训练行为”的测试模式，正是新模块贡献者可以参照的样板。

在projects/项目的 checklist（见 projects/example_project/README.md）中，官方把“单元测试”列为 Milestone 3 的硬性要求，并给出三个阶段：

Milestone 1（PR-ready）：完成代码、基础 docstring 与正确引用、可复现的 checkpoint 与结果；
Milestone 2（成功实现）：提供从头训练结果，能复现论文指标（Kinetics400 动作识别通常允许 ±0.1% 误差）；
Milestone 3（进入核心包）：补齐单元测试、按评审意见重构代码风格、提交metafile.yml与标准化的README.md。

需要特别注意的是：从 checklist 的说明可以推断，贡献代码若复制或修改自其他开源项目，必须在 docstring 中注明来源，且不接受任何 GPL 许可协议的代码片段。

七、提交前的自检清单

综合官方贡献指南与仓库内的项目模板，提交 PR 前建议逐项确认：

分支命名有意义，未在 main 分支直接提交；
大改动已先开 issue 讨论；
pre-commit install已执行，本次提交通过全部钩子检查；
代码通过 flake8 lint，并已由 yapf 格式化；
import 顺序符合 setup.cfg 中 isort 的配置；
docstring 完整、准确，引用了他人的实现与许可协议；
新模块包含单元测试（参照 tests/models/backbones/test_resnet.py 的写法）；
projects/项目包含README.md（含使用方式、结果表、引用与 checklist）、configs/与models/，必要时提供metafile.yml；
C++/CUDA 代码遵循 Google C++ Style Guide；
文档改动已由 mdformat 统一风格，且无拼写错误（codespell 检查）。