BoxMOT 贡献指南:从 Fork 到 Pull Request 的完整开发工作流
BoxMOT 贡献指南:从 Fork 到 Pull Request 的完整开发工作流
BoxMOT 是一个可插拔的多目标跟踪模块库,同时提供 Python 与 C++ 实现,支持轴对齐(AABB)与旋转(OBB)两种检测框。本文以仓库根目录的 CONTRIBUTING.md 为骨架,结合 pyproject.toml、AGENTS.md、.github/workflows/ci.yml 等仓库源码与配置,完整还原一套可落地执行的贡献流程:从 fork 仓库、用 uv 搭建开发环境,到运行 track / generate / eval / tune 四个核心命令验证改动、执行 pytest 与 mkdocs 严格构建,再到按规范提交并打开 Pull Request。读完本文,你将掌握 BoxMOT 的标准化贡献路径,以及如何让自己的改动与仓库的 CI 与基准测试体系保持对齐。
一、贡献前先了解:仓库的五大扩展面
在动手改代码之前,先熟悉仓库的核心扩展区域。根据 docs/contributing/index.md,BoxMOT 主要有五类扩展面:
- 跟踪器:位于 boxmot/trackers,其中 bbox 类跟踪器(如 ByteTrack、BoTSORT、OcSort 等)在
boxmot/trackers/bbox/下,mask 类在boxmot/trackers/mask/,混合类(如 Sam2MOT)在boxmot/trackers/hybrid/; - 原生 C++ 实现:源码在 boxmot/native/cpp/trackers,Python 绑定在 boxmot/native/trackers;
- 配置目录:位于 boxmot/configs,涵盖 trackers、detectors、datasets、experiments、reid 等 YAML 配置;
- 工作流内部与 Python API:通用工作流实现在 boxmot/engine,公开的 Python API 入口在 boxmot/api;
- ReID 模型栈:可复用的 ReID 骨干网络、后端、数据集、训练与导出器在 boxmot/reid,CLI/工作流编排在 boxmot/engine/reid。
理解了这些扩展面,后续分支、改代码、写测试、对齐 CI 时就能快速定位到正确的位置。
二、搭建开发环境:uv 与可编辑安装
CONTRIBUTING.md 建议的依赖管理工具是 uv(Python 包与项目管理器)。全新贡献者按以下顺序准备环境:
# Fork the repository on GitHub
# Then clone your fork locally
git clone <your-fork-url>
cd boxmot
pip install uv
uv sync --all-extras --all-groups # installs boxmot in editable mode with all dependencies
几个关键点值得展开:
-
pip install uv:uv 是独立的二进制工具,安装后可重复执行;即便环境中已有 uv,重复安装也安全。 -
uv sync --all-extras --all-groups:同步所有可选依赖与依赖组。从 pyproject.toml 可以看到仓库定义的组:dev:ipykernel、pre-commit;test:pytest>=8.0.2,<10.0.0、pytest-cov;docs:mkdocs、mkdocs-material、mkdocstrings等文档工具链。
而 extras(可选特性)包括
yolo(ultralytics + yolox)、evolve(超参搜索:optuna、hyperopt、bayesian-optimization 等)、onnx、openvino、tflite、trackeval、research、coreml、rtdetr等,定义见 pyproject.toml。 -
可编辑安装:
uv sync会以 editable 模式安装boxmot,即对源码的修改即时生效,无需重新安装。 -
uv 会在项目根目录创建
.venv。后续所有命令都建议通过uv run执行,避免手动管理虚拟环境激活(见 AGENTS.md)。
此外,AGENTS.md 特别强调:始终以模块方式运行入口点,例如 uv run python -m boxmot.engine.cli --help,而不要直接 python boxmot/engine/cli.py,否则可能触发 ModuleNotFoundError: boxmot 之类的导入错误。
三、创建分支:短小、描述性命名
环境就绪后,从干净的基线上创建功能分支:
git checkout -b feature/short-desc
AGENTS.md 对分支命名给出了更细的规范,推荐使用 <type>/<short-description> 形式,例如:
feature/add-login-page(新功能)fix/handle-null-user(缺陷修复)refactor/simplify-auth-flow(重构)docs/update-readme(仅文档)test/、chore/、ci/、build/、deps/、perf/等类型同样被认可
要避免 update、changes、stuff、fixes、wip 这类模糊命名。同时保持改动聚焦:一个逻辑变更对应一个 PR,不要混入无关修改(见 AGENTS.md)。
四、验证改动:四个核心 CLI 命令
开发过程中,CONTRIBUTING.md 建议在改动影响的功能范围上运行验证命令,四个命令覆盖了 BoxMOT 的主要工作模式:
# Run functionality where changes were introduced
uv run boxmot track --detector yolov8x --reid osnet_x0_25_msmt17 --tracker bytetrack --source my_video.mp4 --classes 0
uv run boxmot generate --detector yolov8x --reid osnet_x0_25_msmt17 --source path/to/dataset --classes 0
uv run boxmot eval --dataset mot17 --split ablation --tracker bytetrack
uv run boxmot tune --experiment mot17-ablation-yolox-lmbn --tracker bytetrack
结合仓库的 CLI 实现与 CI 脚本,可以进一步理解每个命令的用途与参数语义(入口见 boxmot/engine/cli.py,boxmot 脚本注册于 pyproject.toml):
| 命令 | 职责 | 关键参数说明 |
|---|---|---|
track |
对单个视频/图片/目录执行跟踪推理 | --detector 检测器(权重或名称)、--reid ReID 权重、--tracker 跟踪器名(如 bytetrack)、--source 输入源、--classes 过滤类别、--imgsz 推理尺寸、--device(如 cpu) |
generate |
为数据集批量预生成检测框与 ReID 嵌入,供后续 eval 复用 | 与 track 类似的检测器/ReID 参数,外加 --experiment 指定实验 ID |
eval |
在数据集上评估跟踪指标(HOTA / MOTA / IDF1 等) | --dataset(如 mot17)、--split(如 ablation)、--tracker、--experiment、--ci(CI 模式输出机器可读 JSON) |
tune |
对跟踪器超参数执行进化/搜索优化 | --experiment、--tracker、--n-trials(试验次数)、--ci |
这些命令与 CI 中的实际调用高度一致。例如 .github/workflows/ci.yml 的 trackers 作业就是逐一遍历 TRACKERS 列表,对每个跟踪器执行 boxmot track --detector "$BOXMOT_CI_DETECTOR" --imgsz 320 --tracker "$tracker" --source "$IMG" --verbose,其中需要 ReID 的跟踪器(botsort deepocsort strongsort boosttrack occluboost hybridsort)会额外追加 --reid osnet_x0_25_msmt17.pt。metrics 作业则完整演示了 generate → eval 的评估链路(ci.yml)。
小贴士:
--imgsz 320是 CI 中普遍采用的轻量推理尺寸,可在不改变功能语义的前提下大幅缩短单帧耗时;本地验证也可照此加速。
五、运行测试:uv run pytest
改动完成后,运行仓库测试套件:
uv run pytest
pytest 配置 将测试根目录指向 tests/,并排除 boxmot/datasets/mot、boxmot/datasets/reid、runs 等不需要采集的路径。测试覆盖范围很广,按 tests 目录组织为:
tests/unit/:单元测试,覆盖 API(tests/unit/api)、数据层、检测器契约、运动模型、ReID 训练、原生 C++ 绑定(tests/unit/native)、跟踪器注册与契约(tests/unit/trackers)等;tests/ci/:CI 冒烟测试,例如 tests/ci/python_api_smoke.py,用 CPU 环境真实跑一遍BoxMOT.track、BoxMOT.val与ReIDModel.export主流程。
如果完整套件太重,AGENTS.md 建议至少运行与改动相关的测试,例如:
uv run pytest tests/unit/engine/test_cli.py
uv run pytest tests/path/to/affected_module_tests.py
注意 CI 主测试作业(见 ci.yml)会忽略 tests/ci、tests/unit/native、tests/unit/tools 并设定 25% 的覆盖率下限(COVERAGE_FAIL_UNDER),因为这些专项作业有各自独立的 CI 阶段。
六、文档改动:mkdocs 严格构建
如果改动涉及文档,CONTRIBUTING.md 要求通过严格模式构建文档站点:
uv run mkdocs build --strict
BoxMOT 使用 MkDocs Material 主题,站点结构定义在 mkdocs.yml,包含 Quickstart、Getting Started、Modes、Configuration、Trackers、Concepts、Guides、Native C++、Python API、Contributing 等导航分区。--strict 会把警告升级为错误,确保文档中的内部链接、mdocstrings 提取等全部有效。
这与 CI 中的 docs.yml 工作流对应:文档作业安装 --group docs 后执行 uv run mkdocs build --strict(见 docs/contributing/ci.md)。同时记住 AGENTS.md 的提醒:改动 CLI 选项、默认值、命令时,必须同步更新 README.md、docs/、examples/ 中的相关示例。
七、提交与推送:规范化的 commit message
# Commit & push
git add .
git commit -m "type: summary"
git push origin feature/short-desc
commit message 必须以类型前缀开头。AGENTS.md 与 .github/workflows/label.yml 约定的类型包括:
feat:新功能fix:缺陷修复refactor:内部重构docs:仅文档ci:CI/工具链改动perf:性能优化
每个 commit 应代表一个连贯的变更,避免混合无关编辑。PR 描述则应包含:用户可见改动的简短摘要、Testing 小节(说明跑了哪些命令、哪些因环境限制未跑)、后续工作或已知限制。
八、打开 Pull Request 与 CI 对齐
推送分支后,在 GitHub 上进入自己的 fork 点击 "Contribute" 发起 PR。提交前,务必检查你的改动是否触及 CI 敏感区域。docs/contributing/ci.md 列出典型的高敏感改动:
- 新增跟踪器;
- 重命名跟踪器标识符;
- 修改基准测试作业使用的实验 ID;
- 修改基准表/矩阵中的默认跟踪器集合;
- 修改 ReID、mask、OBB 或原生后端的依赖要求。
CI 触发机制(见 docs/contributing/ci.md 与各工作流文件):
| 工作流 | 当前触发条件 |
|---|---|
| .github/workflows/ci.yml | 推送至 master、PR 目标为 master |
| .github/workflows/docs.yml | 所有分支推送 + 手动触发;仅在 master 部署 |
| .github/workflows/benchmark.yml | 推送至 main、PR 目标为 main、手动触发 |
需要注意两个易踩的坑:其一,直接向特性分支推送不会触发 ci.yml,必须打开目标为 master 的 PR(或通过正常合并流程进入 master);当前 ci.yml 没有路径过滤(path filters)。其二,仓库的集成分支是 master,而 benchmark.yml 的自动触发过滤在 main,因此在当前仓库中基准工作流主要通过手动触发运行。
主工作流 ci.yml 覆盖的作业面非常广(ci.yml):跟踪器冒烟(trackers)、原生构建(native_build)、C++ 后端冒烟(cpp_trackers)、超参调优(tune)、指标评测与 TrackEval 对齐(metrics)、ReID 训练/评估(reid)、OBB 支持矩阵(obb)、姿态/分割/多检测器集成(pose / seg / yolos)、导出引擎(export)、Python API 冒烟(python_api)、完整 pytest 套件(tests),最终由 check-failures 作业汇总各作业结果并生成 CI 摘要表。
依赖安装统一由 .github/scripts/uv_ci_install.sh 完成:脚本接收 editable 规格(如 ".[yolo]")与额外参数(如 --group test),基于 .venv 使用 CPU 版 torch(--torch-backend cpu)安装,保证 CI 环境与本地一致且不拉入 CUDA 依赖。如果你的改动引入了新的运行时依赖,应让对应作业最小化安装所需的 extras 与 groups,而不是全量安装。
对齐清单:若某个跟踪器在文档中被声明为受支持,那么相关测试与工作流覆盖也应匹配这一支持级别。具体需要检查 ci.yml 中的 TRACKERS、REID_TRACKERS、EXPECTED_OBB_TRACKERS、CPP_TRACKERS 环境列表,以及 benchmark.yml 中的显式跟踪器/后端矩阵;mask 类跟踪器可能需要专用的 mask 源或模型,而非通用的边界框冒烟命令。
九、新增跟踪器时的最小清单
若你的贡献是"新增一个跟踪器",docs/contributing/add-tracker.md 给出了可对照执行的清单,这里概括核心步骤:
- 在对应模态目录新增模块:
boxmot/trackers/bbox/<name>.py、boxmot/trackers/mask/<name>/或boxmot/trackers/hybrid/<name>/; - 实现继承
BaseTracker的类并定义update(); - 在 boxmot/trackers/registry.py 的
TRACKER_DEFINITIONS中注册TrackerDefinition(TRACKER_MAPPING、REID_TRACKERS、类名映射均由该定义派生,见 registry.py); - 从模态包导出类(如
boxmot/trackers/bbox/__init__.py); - 添加 boxmot/configs/trackers 下的
<name>.yaml默认配置; - 添加跟踪器文档页并接入 mkdocs.yml 导航;
- 扩展
tests/unit/trackers/下的注册/契约测试与tests/test_config.py中的跟踪器列表; - 若需纳入基准,更新
.github/workflows/中的跟踪器/ReID/mask/OBB/基准列表。
若同时提供原生 C++ 后端,还需在 boxmot/native/cpp/trackers 添加源码、在 boxmot/native/cpp/CMakeLists.txt 登记子目录、在 boxmot/native/trackers 添加 Python 封装、在 boxmot/native/registry.py 注册 live/replay 后端,并在 tests/unit/native/trackers 下补充原生封装测试。
十、总结:一条完整的贡献路径
回顾整个流程,BoxMOT 的标准贡献路径是:
- 了解扩展面 → 定位改动落在哪个模块;
- 搭建环境 →
pip install uv+uv sync --all-extras --all-groups,获得可编辑安装的开发环境; - 建分支 →
git checkout -b feature/short-desc,遵循类型前缀命名; - 开发并验证 → 在改动范围内运行
track/generate/eval/tune四个命令之一; - 跑测试 →
uv run pytest,必要时只跑受影响模块; - 文档 → 涉及文档时用
uv run mkdocs build --strict严格校验; - 提交 →
type: summary规范 commit 并推送; - 开 PR → 检查 CI 敏感改动,确认工作流矩阵与文档声明一致。
遵循这一流程,既能保证改动的质量与可验证性,也能让贡献与仓库的 CI、基准测试与文档体系保持一致,减少来回 review 的损耗。