YOLO Vision 2026：

开发工作流程 💻#

本指南介绍了 Ultralytics 员工和贡献者如何在各种 Ultralytics 项目（包括 YOLO 及相关代码库）中规划、实现、审阅、测试和合并更改。

该工作流程旨在保持轻量化：确保更改聚焦、简化审查、运行必要的检查，并为团队成员提供足够的背景信息以了解后续决策。

行为准则 🤝#

所有贡献者必须遵循行为准则。在 Issue、PR、评审、内部讨论以及公开社区空间中，应保持尊重、清晰和专业。有关公共贡献的要求，请参阅官方贡献指南。

协作节奏 🛰️#

  • 核心工作日（周二/周三/周四）： 利用这些时间进行代码审查、设计讨论、调试会话以及需要同步协作的决策。
  • 周一/周五： 优先进行深度工作、编写更新、准备 PR 和异步审查。如果需要同步对齐，请将关键阻碍事项移至下一个核心工作日处理。
  • 站会与审查： 将站会时间限制在 15 分钟内。尽可能在核心工作日安排设计和架构审查。
  • 决策记录： 将重要决策记录在 PR 描述、Issue、文档或运行手册中，以免上下文在聊天中丢失。

范围与所有权 🧭#

本工作流程适用于产品、Ultralytics 平台、YOLO、基础设施、文档、自动化以及安全敏感系统等各个领域的 Ultralytics 工程工作。各个代码库可能会添加更严格的要求，但不应削弱本页面中的基准期望。

每一项工作都应有明确的负责人：

  • 作者： 实施更改，保持 PR 更新，并提供验证证据。
  • 审查者： 确认正确性、可维护性、风险以及对文档的影响。
  • 领域所有者： 审查涉及专业领域（如模型行为、基础设施、安全、隐私、许可或面向客户的工作流程）的更改。
  • 分类所有者： 将传入的 Issue、事件、漏洞报告和维护工作分配给正确的负责人。
分类期望

新的工程工作应根据影响、优先级、所有权和风险进行分类。涉及安全、生产、客户影响和合规性的工作应有明确的负责人和后续跟进路径，而不是作为未分配的 Issue 或聊天线程搁置。

Pull Request 流程 🔄#

flowchart TD
    A[Fork or Sync Repository]:::start --> B[Create Feature Branch]:::proc
    B --> C[Make Changes]:::proc
    C --> D[Run Tests Locally]:::proc
    D --> E[Commit Changes]:::proc
    E --> F[Create Pull Request]:::proc
    F --> G[Sign CLA]:::proc
    G --> H{Review}:::decide
    H -->|Changes Requested| I[Address Feedback]:::proc
    I --> H
    H -->|Approved| J[Merge!]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff

Fork 或同步存储库#

外部贡献者应将相关的 Ultralytics 仓库（例如 ultralytics/ultralytics）fork 到你的 GitHub 账户。

具有写权限的员工在创建分支前应同步 main：

# External contributors
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics

# Employees with write access
git checkout main
git pull origin main

创建功能分支#

创建一个分支，使用清晰、具描述性且能反映工作内容的名称：

git checkout -b fix-issue-123
分支命名规范
  • fix-export-timeout 用于修复 Bug
  • add-training-metrics 用于新功能
  • update-docs-training 用于文档
  • ci-link-check 用于自动化或基础设施

进行更改#

遵循指南

遵循存储库现有的模式和风格

避免错误

避免出现新的警告、回归或不相关的更改

保持聚焦

将 PR 范围限制在一个明确的结果上

测试更改#

必须测试

在请求审查前，请运行与更改风险相符的检查：

pytest tests/

为新功能添加测试，并为 Bug 修复添加回归测试。如果无法在本地运行相关的检查，请在 PR 中说明原因并提供手动验证备注。

了解详情：测试要求、模型验证、CI 工作流程

提交更改#

提交Commit时，请使用简洁、具描述性的信息：

git commit -m "Fix #123: Corrected calculation error"
提交信息最佳实践
  • 使用现在时态（“Add feature” 而不是 “Added feature”）
  • 适用时引用 Issue 编号
  • 主题行保持在 72 个字符以内

创建 Pull Request#

从你的分支向 main Submit PR：

  • 标题清晰，描述了更改内容
  • 描述涵盖了目的、范围和验证
  • 链接了相关的 Issue
  • 明确了所有者和所需的审查者
  • 标注了风险、兼容性问题或部署步骤
  • 包含 UI 更改的截图
  • 测试在本地通过

签署 CLA#

合并前必须签署

外部贡献者必须签署贡献者许可协议 (CLA)，以确保贡献根据 AGPL-3.0 许可证获得适当许可。

提交 PR 后，添加以下评论：

I have read the CLA Document and I sign the CLA

CLA 机器人将引导你完成整个流程。有关许可的更多详情，请参阅我们的贡献指南。

处理审查反馈#

回复审查者意见，推送更新，并在范围更改时保持 PR 描述为最新。在请求重新审查之前，解决所有阻碍性反馈。

Google 风格文档字符串 📝#

在代码库要求的位置，公共函数和类应使用谷歌风格文档字符串。保持文档字符串准确、简洁且对未来的维护者有用。

标准函数#

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

命名返回#

def example_function(arg1, arg2=4):
    """Example function with named return.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

多个返回值#

def example_function(arg1, arg2=4):
    """Example function with multiple returns.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

重要： 当函数返回多个值时，请分别记录每个返回值，不要将重要的细节隐藏在通用的元组描述中。

✅ 正确：

Returns:
    (np.ndarray): Predicted masks with shape HxWxN.
    (list): Confidence scores for each instance.

❌ 错误：

Returns:
    (tuple): Tuple containing:
        - (np.ndarray): Predicted masks with shape HxWxN.
        - (list): Confidence scores for each instance.

带有类型提示#

def example_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with type hints.

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(1, 1)  # True
    """
    return arg1 == arg2

单行文档字符串#

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

代码标准 📐#

Python 风格#

标准要求示例
行宽遵循存储库配置，通常为 120 个字符保持行可读且易于扫描
文档字符串谷歌风格在有帮助的地方使用类型和示例
导入优先使用 pathlib 而非手动处理路径字符串现代、跨平台的路径
类型提示在能够提高清晰度时使用公共 API、复杂结构、返回数据
函数保持聚焦且可测试将复杂的逻辑拆分为命名辅助函数

代码质量#

质量核对清单
  • 没有未使用的导入或变量
  • 保持命名一致 (lowercase_with_underscores)
  • 变量名清晰；避免使用单个字母，循环计数器除外

最佳实践#

避免重复

复用现有的辅助函数和模式

更小的变更

相比广泛的混合变更，更倾向于集中式的 PR

简化

在能提升清晰度时移除复杂性

兼容性

保持公共 API 和用户工作流不变

添加测试

覆盖新行为和回归测试

一致的格式

遵循代码仓库的格式化工具规范

安全框架 🛡️#

Ultralytics 工程实践应与公认的安全开发指导保持一致，包括 OWASP 安全软件开发生命周期、OWASP 应用安全验证标准以及 OWASP Top 10。团队在计划安全设计、评审、测试和修复工作时应参考这些内容。

资产管理 🗂️#

工程资产应有明确的负责人和可靠的事实来源。这包括代码仓库、服务、云资源、CI/CD 运行器、域名、数据集、模型制品、API 密钥、机密信息、部署环境以及第三方集成。

在创建、变更或弃用资产时：

  • 指定负责人和维护联系人。
  • 记录用途、环境、访问需求和生命周期状态。
  • 审核访问权限和最小特权原则。
  • 确保机密信息和凭证不出现在代码、日志、截图和文档中。
  • 当所有权或行为发生变化时，更新操作手册、架构图、清单或文档。
  • 弃用未使用的资产以减少安全性、成本和维护风险。

文档评审 📝#

文档应与当前的角色、所有权、工作流和安全预期保持一致。当流程发生变化时，尽可能在同一个 PR 中更新相关的手册页面、公共文档、操作手册或 README。

文档审核人员应检查：

  • 角色名称、所有权和升级路径是否为最新。
  • 安全、合规和许可条款是否符合当前政策。
  • 链接、架构图、命令和截图是否依然反映了产品或工作流的现状。
  • 新增或变更的流程是否包含明确的负责人和评审节奏。
  • 公共文档是否未暴露仅限内部的信息、机密、客户数据或敏感的操作细节。

测试要求 ✅#

所有 PR 都应包含与变更风险相匹配的验证：

pytest tests/

# When coverage is relevant
pytest --cov=ultralytics tests/

对于模型行为的更改，在实际可行的情况下，请包含数据集、模型、命令、硬件以及更改前后的指标。对于文档更改，请在本地构建文档，并为布局更改附上截图或预览链接。有关 CI 的详细信息，请参阅 CI/测试。

代码评审准则 👀#

贡献者须知#

  • 保持 PR 专注于单一功能、修复或文档更新。
  • 解释问题、解决方案、验证方法和风险。
  • 及时响应反馈。
  • 将评审视为工作的一部分，而非个人判断。
  • 如果工作范围发生变化，请更新 PR 描述。

审核人须知#

  • 在一到两个工作日内完成评审，或迅速重定向给他人。
  • 检查新行为的测试和验证证据。
  • 审核文档更新中对用户可见的变更。
  • 评估对性能、兼容性、安全性、隐私和可维护性的影响。
  • 验证相关的 CI 检查是否通过。
  • 提供建设性且具体的反馈。
  • 区分阻塞性问题和建议性优化。

Git 最佳实践 🌳#

提交 (Commits)#

  • 使用现在时态：例如使用 "Add feature" 而非 "Added feature"。
  • 编写清晰、描述性的消息。
  • 保持提交内容专注且逻辑连贯。
  • 避免将纯格式化的修改与行为变更混在一起。

分支 (Branches)#

  • 在创建分支之前拉取最新的 main。
  • 如果分支已经落后，请在最终提交前对 main 进行变基（rebase）或合并。
  • 合并后请删除分支。

报告 Bug 🐞#

通过 GitHub Issues 报告 Bug：

  1. 首先检查现有问题
  2. 提供最小可复现示例
  3. 描述环境：操作系统、Python 版本、库版本、硬件（使用 yolo checks 进行诊断）
  4. 解释预期行为与实际行为的差异并附上错误消息

有关常见问题及解决方法，请参阅我们的故障排除指南。

许可证 📜#

许多 Ultralytics 代码库使用 AGPL-3.0 许可证。如果你在项目中使用 AGPL 许可的 Ultralytics 代码，你的项目可能也需要根据 AGPL-3.0 开源。如果你需要闭源或商业使用，请查阅企业许可证。

资源 📚#

贡献者
GLglenn-jocher13AMambitious-octopus1