DeepLabCut 开源贡献指南：从开发环境搭建到 Pull Request 合并的完整工程实践

人工智能深度学习计算机视觉科研【免费下载链接】DeepLabCutOfficial implementation of DeepLabCut: Markerless pose estimation of user-defined features with deep learning for all animals incl. humans项目地址https://gitcode.com/gh_mirrors/de/DeepLabCut点击查看免费下载DeepLabCut 是一个基于深度学习的无标记姿态估计开源工具箱支持包括人类在内的所有动物自定义特征追踪。本指南以仓库根目录的 CONTRIBUTING.md 为骨架结合 pyproject.toml、.pre-commit-config.yaml、reinstall.sh、CI 工作流与测试目录等真实仓库实现系统讲解贡献者从零参与 DeepLabCut 开发所需的完整流程本地开发环境搭建、代码风格检查、测试运行、Pull Request 提交流程以及许可声明维护。读完本文你将能够独立完成一次符合 DeepLabCut 工程规范的贡献提交。一、你可以为 DeepLabCut 贡献什么DeepLabCut 欢迎 bug 修复、新功能、文档改进、测试补充与日常维护等各类贡献。根据 CONTRIBUTING.md社区常见的贡献方式包括修复 Bug定位并修复分析管线、GUI、配置解析等环节的问题改进文档更新 docs/ 或 dev-docs/ 中的用户指南、开发者指南与 API 文档添加测试为已有功能补测试或在新增功能时同步编写测试改进示例维护 examples/ 下的 Jupyter Notebook 与testscript_*.py脚本重构或清理代码仓库内置了多种质量工具见后文工具链本身也欢迎改进提议或实现新功能包括新模型架构、新推理后端、GUI 增强等。DeepLabCut 尤其鼓励在开源软件中代表性不足背景的开发者参与。若想在提交 Pull Request 前讨论想法可以直接开 Discussion 或 Issue。从仓库结构看deeplabcut/ 下按功能划分了core、create_project、generate_training_dataset、gui、pose_estimation_pytorch、pose_estimation_tensorflow、pose_tracking_pytorch、post_processing、modelzoo等模块你可以根据兴趣选择切入点。二、开发环境搭建让本地源码成为可导入的包2.1 Fork 并 Clone 仓库贡献的第一步是在 GitHub 上 Fork DeepLabCut 仓库然后克隆自己的 Forkgit clone https://github.com/your-username/DeepLabCut.git cd DeepLabCut如果你不熟悉 GitHub 协作流程官方提供的 GitHub Guides 是很好的起点。2.2 创建 Python 环境并安装开发依赖DeepLabCut 的依赖声明全部集中在 pyproject.toml 中项目采用dependency groups依赖组而非传统的 extras 来组织开发工具。与文档对应dev组定义如下[dependency-groups] dev [ coverage, nbformat5, pre-commit, pytest, pytest-cov, ruff, ]即dev组一次性提供格式化ruff、测试pytest、pytest-cov、coverage与提交检查pre-commit所需的全部工具。安装方式有两种使用 uv推荐仓库根目录已有 uv.lock 锁定依赖uv sync --group dev使用 pip例如在 conda 环境中pip install -e . --group dev-eeditable/development 模式保证本地 checkout 的源码会被 Python 直接导入改代码无需重新安装。如果你使用其他环境管理器请同样以可编辑模式安装并显式带上dev依赖组。值得说明的是pyproject.toml 中除了dev还定义了dev-docsmkdocs 文档工具链、gui-devpytest-qt、knowledge-index文档知识索引工具链等附加组CI 中运行pip install -e .[extras] --group dev --group knowledge-index见 .github/workflows/python-package.yml本地开发时可根据需要选择。此外TensorFlow 后端相关的tf、tf-cu11、tf-cu12、tf-latest、apple_mchips等 extras 互斥安装时只能选择一个详见 pyproject.toml 中的[tool.uv] conflicts声明。2.3 验证你正在使用本地源码环境就绪后可以验证 Python 导入的是本地 checkout 而非已安装的发行版python -c import deeplabcut; print(deeplabcut.__file__)如果打印出的路径指向你的克隆目录说明 editable 安装生效。是否使用ipython或 Jupyter 完全看个人偏好仓库不对此做强制要求。2.4 修改了打包资源时运行 reinstall.sh 刷新安装常规代码修改在 editable 模式下即时生效但 DeepLabCut 的部分资源YAML 配置、QSS 样式、图标、示例脚本等是在安装阶段被拷贝进包内的。仓库根目录的 reinstall.sh 用于重新构建并安装整个包其内容为pip uninstall deeplabcut rm -rf dist/ build/ *.egg-info python3 setup.py sdist bdist_wheel pip install dist/deeplabcut-3.0.0-py3-none-any.whl正如 CONTRIBUTING.md 中提示的这不是简单的pip install -e .因为有些资源在安装期间才被复制必须重新构建 wheel 才能刷新。从 pyproject.toml 的[tool.setuptools.package-data]可以看出安装时会打包*.yaml、*.yml、*.json、*.qss、*.png、*.md、*.sh等资源文件这正是安装时拷贝资源的底层原因。另需留意脚本中pip install引用的 wheel 文件名硬编码了版本号3.0.0而当前 deeplabcut/version.py 中的__version__为3.0.2实际产物文件名以构建时版本为准若安装步骤报找不到文件可改为pip install dist/deeplabcut-*.whl。三、代码风格与 pre-commit提交前的自动化质量门3.1 安装 pre-commit 钩子DeepLabCut 使用pre-commit在代码提交前自动执行格式化与各类检查。在克隆目录中执行一次pre-commit install之后每次git commit都会运行配置好的钩子。在打开 Pull Request 之前务必先运行 pre-commit这能尽早捕获格式、导入顺序、空白字符、YAML 等问题大幅加速代码评审。3.2 pre-commit 钩子清单详解仓库根目录的 .pre-commit-config.yaml 定义了完整的钩子集合按仓库分类如下钩子仓库版本钩子作用pre-commit/pre-commit-hooksv6.0.0check-added-large-files、check-yaml、check-toml、check-merge-conflict、name-tests-test--pytest-test-first、check-json基础格式与冲突检查同上本地修改型v6.0.0end-of-file-fixer、trailing-whitespace自动修正文件结尾与行尾空白仅本地运行tox-dev/pyproject-fmtv2.19.0pyproject-fmt格式化 pyproject.toml仅本地运行abravalheri/validate-pyprojectv0.25validate-pyproject校验 pyproject.toml 语法astral-sh/ruff-pre-commitv0.15.6ruff-check--fix --unsafe-fixes、ruff-formatPython 代码 lint 与格式化本地CI 侧另有--output-formatgithub、--check --diff的 check-only 变体hukkin/mdformat1.0.0mdformatdocs 用mdformat-mystdev-docs 用mdformat-mkdocsMarkdown 格式化分别适配 docs/ 与 dev-docs/ 两种文档方言local—dlc-docs-notebooks-check运行 tools/docs_and_notebooks_check.py校验文档与 Notebook 的一致性并做 nbformat 校验从配置可以看到一个重要的设计会修改文件的钩子如end-of-file-fixer、ruff-check --fix、mdformat只绑定pre-commit阶段仅在本地提交时执行check-only 的钩子同时绑定pre-commit与manual阶段供 CI 以--hook-stage manual只读运行。CI 侧的执行逻辑可见 .github/workflows/format.yml它检测 PR 变更文件仅对变更文件运行 pre-commit 的 manual 阶段并在失败时通过 tools/ruff_report.py 生成 Markdown 格式的 Ruff 报告附到工作流摘要中。3.3 Ruff 规则约定pyproject.toml 中的[tool.ruff]段定义了代码风格约定目标 Python 版本py310与项目要求的requires-python 3.10一致行长限制120 字符line-length 120启用的 lint 规则集Epycodestyle 错误、Fpyflakes、Bbugbear、Iisort 导入排序、UPpyupgrade、PIEflake8-pie忽略E741、B007docstring 遵循 Google 约定[tool.ruff.lint.pydocstyle] convention google对__init__.py、deeplabcut/gui/window.py 及 TensorFlow legacy 库中的部分文件做了按文件的忽略豁免per-file-ignores因为其中使用了from module import *等历史遗留写法。四、测试在提交前验证你的改动4.1 本地运行测试在项目根目录运行pytest testsCONTRIBUTING.md 明确指出Pull Request 会在 CI 中自动验证因此本地全量跑测试并非硬性要求但提前发现问题是加速评审的最有效方式。4.2 pytest 配置与测试标记pytest 的配置同样位于 pyproject.toml 的[tool.pytest.ini_options]中[tool.pytest.ini_options] pythonpath [ . ] # 将仓库根目录加入 sys.path便于导入 tools/ markers [ require_models: mark test as requiring models to run, fmpose3d: tests for fmpose3d integration, unittest: fast unit-level tests, functional: functional/integration-style tests, deprecated: tests for deprecated APIs kept for backward-compatibility, ]测试按标记分层快速单元测试unittest、功能/集成测试functional、需要真实模型权重的测试require_models、fmpose3d 集成测试fmpose3d以及针对已弃用 API 的回归测试deprecated。仓库中可见大量使用示例例如 tests/pose_estimation_pytorch/modelzoo/test_fmpose_integration.py 同时使用unittest与functional标记tests/gui/test_main_window_config.py 使用functionaltests/test_auxiliaryfunctions.py 使用deprecated。分层标记便于在 CI 中按需选择测试范围。4.3 测试数据与共享 Fixturetests/ 目录按功能模块组织core/、create_project/、gui/、pose_estimation_pytorch/、utils/等并配有 tests/conftest.py 提供会话级共享测试数据ensure_test_data这个 autouse fixture 会在测试会话启动时检查tests/data/下的必需文件如dets.pickle、outputs.pickle、image.png、trimouse_assemblies.pickle、montblanc_tracks.h5等缺失时自动从 DeepLabCut 的 UnitTestData 数据源下载并解压。此外还提供了ground_truth_detections、model_outputs、sample_image、real_assemblies、real_tracklets、evaluation_data_and_metadata等一系列复用 fixture新增测试时可直接复用。4.4 CI 中的测试矩阵核心测试工作流是 .github/workflows/python-package.yml它通过可复用的workflow_call接口被 .github/workflows/intelligent-testing.yml 调用支持多 OS × Python 版本的矩阵测试。CI 会使用 conda 设置 Python 环境安装 ffmpegLinux/macOS 用包管理器Windows 用固定版本的预编译构建并校验 SHA256以 editable 模式安装包并附带--group dev --group knowledge-index根据FULL_SUITE或PYTEST_PATHS_JSON选择运行全量 pytest 或定向测试路径运行examples/testscript_*.py功能脚本如 examples/testscript_tensorflow_single_animal.py、examples/testscript_pytorch_multi_animal.py 等。五、Pull Request 指南5.1 提交 PR 时的检查清单根据 CONTRIBUTING.md提交 Pull Request 时请确保清晰描述变更内容与动机改了什么、为什么改关联相关 Issue便于追踪上下文行为发生变化时同步更新 docstrings 与文档适当时添加或更新测试当小示例有助于评审者理解/验证时在 PR 中附上。项目建议小而聚焦的 PR多个小 PR 通常比一个巨型 PR 更容易评审也更易合并。5.2 草稿 PRDraft Pull RequestDeepLabCut 使用 Draft PR 标记进行中的工作在草稿 PR 上同样可以请求评审与反馈项目鼓励这样做以便尽早获得建议草稿状态与代码质量或合并潜力无关只是表明工作尚未准备好进行最终评审与合并大多数 PR 在其生命周期的大部分时间内都处于草稿状态这是正常且被预期的。5.3 审查流程维护者会评审你的 Pull Request。PR 描述中无需提供具体的发布排期贡献会按维护者的精力与容量逐步评审合并。如果你不确定改动该放哪个模块、如何组织结构直接开一个草稿 PR 询问即可。六、文档改进文档改进始终受欢迎。如果你的改动会影响用户请同步更新相关文档、示例或内联 docstring使行为易于被发现和理解。DeepLabCut 的文档分为两棵树docs/面向用户的手册、教程、API 参考与 dev-docs/面向开发者的指南二者使用不同的 MkDocs/Markdown 方言。因此在 .pre-commit-config.yaml 中mdformat钩子为两棵树分别配置了mdformat-myst与mdformat-mkdocs插件后者还带--ignore-missing-references参数以避免链接被错误改写。此外本地钩子dlc-docs-notebooks-check会校验 docs/ 与 examples/ 下的 Notebook/Markdown 是否过期配置见 tools/docs_and_notebooks_report_config.yml所以文档或 Notebook 的改动同样需要跑过 pre-commit。七、代码头部与许可声明7.1 规范化代码头部如果需要统一代码文件头的版权声明可运行python tools/update_license_headers.py该脚本的实现位于 tools/update_license_headers.py它读取 NOTICE.yml 中的配置按每条规则的include/exclude模式收集文件并调用licenseheaders工具写入对应的头部模板。NOTICE.yml 定义了多组头部规则主仓库许可适用于deeplabcut/**/*.py、tests/**/*.py、examples/**/*.py、docs/**/*.py等声明 LGPL-3.0-or-laterDeeperCut 改编文件针对 deeplabcut/pose_estimation_tensorflow/ 下从 Eldar Insafutdinov 的 pose-tensorflow 改编的文件额外注明Adapted from DeeperCutTensorFlow 许可对引入的 TensorFlow 代码注明 Apache License 2.0 归属。7.2 不要修改的许可文件贡献者被明确要求不要更新 NOTICE.yml 与 LICENSE 文件许可与版权的调整属于维护者职责范围。八、需要帮助时怎么办如果对改动范围不确定直接开一个 Issue 或草稿 PR 提问即可。项目宁愿尽早提供帮助也不愿你在错误的方向上浪费时间。也欢迎通过 Feature requests 类型的 Issue 讨论实现细节或获取初步反馈。附录贡献前检查清单速览Fork 仓库并 clone 到本地用uv sync --group dev或pip install -e . --group dev搭建开发环境修改代码后用python -c import deeplabcut; print(deeplabcut.__file__)确认使用的是本地源码改动涉及打包资源时运行./reinstall.sh重建 wheel首次使用前执行pre-commit install每次提交前确保 pre-commit 通过提交 PR 前运行pytest testsCI 会自动跑完整测试矩阵同步更新 docstrings、文档与测试附上必要的使用示例保持 PR 小而聚焦需要提前反馈时使用 Draft PR不要修改 NOTICE.yml 与 LICENSE 文件不确定的地方优先开 Issue 或草稿 PR 询问。按此流程你的贡献将能顺利通过 pre-commit 与 CI 校验快速进入 DeepLabCut 维护者的评审视线。赞分享人工智能深度学习计算机视觉科研【免费下载链接】DeepLabCutOfficial implementation of DeepLabCut: Markerless pose estimation of user-defined features with deep learning for all animals incl. humans项目地址https://gitcode.com/gh_mirrors/de/DeepLabCut点击查看免费下载相关推荐Guardrails 贡献指南从环境搭建、开发工作流到 Pull Request 合并的完整工程实践Guardrails 贡献指南从环境搭建、开发工作流到 Pull Request 合并的完整工程实践 Guardrails 是一个面向大语言模型的 PythoAI 安全治理模型安全AI 应用OGX 贡献指南从环境搭建到合并 Pull Request 的完整开发流程OGX 贡献指南从环境搭建到合并 Pull Request 的完整开发流程 OGXOpen GenAI Stack是一个开源的、OpenAI 兼容的 APAI应用API网关后端模型推理服务Linutil 贡献指南从本地开发环境搭建到合并 Pull Request 的完整实践Linutil 贡献指南从本地开发环境搭建到合并 Pull Request 的完整实践 导读 本文以 Linutil 官方《Contributing GuidCLI运维上一篇OK-WW技术方案解析基于图像识别的鸣潮自动化效率革命下一篇WorkshopDL打破平台壁垒的Steam创意工坊模组下载解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考