Meet YOLO26: next-gen vision AI.

Link to this section开发工作流程 💻#

本指南涵盖了 Ultralytics 员工和贡献者如何规划、实施、审查、测试并合并 Ultralytics 项目(包括 YOLO 及相关仓库)中的变更。

工作流程力求精简:保持变更目标明确,简化审查流程,执行适当的检查,并为团队成员保留足够的上下文以供后续理解决策。

Link to this section行为准则 🤝#

所有贡献者必须遵守 Code of Conduct。在 Issue、PR、审查、内部讨论以及公共社区空间中,我们期望大家保持尊重、清晰和专业。关于公开贡献的要求,请参阅 Official Contributing Guide

Link to this section协作节奏 🛰️#

  • 锚定日(周二/周三/周四): 利用这些时间进行代码审查、设计讨论、调试会议以及需要同步协作的决策。
  • 周一/周五: 优先进行深度工作、书面更新、PR 准备和异步审查。当需要同步一致性时,将关键阻塞问题移至下一个锚定日处理。
  • 站会与审查: 将站会时间严格控制在 15 分钟以内。尽可能在锚定日安排设计和架构审查。
  • 决策记录: 将重要决策记录在 PR 描述、Issue、文档或运行手册中,以免上下文在聊天中丢失。

Link to this section范围与所有权 🧭#

此工作流程适用于 Ultralytics 在产品、Ultralytics Platform、YOLO、基础设施、文档、自动化和安全敏感系统方面的工程工作。各个仓库可以增加更严格的要求,但不得削弱本页面中的基准期望。

每个工作项都应有明确的所有者:

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

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

Link to this sectionPull Request 流程 🔄#

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

    style A fill:#e1f5ff
    style J fill:#d4edda
    style G fill:#fff3cd

Link to this sectionFork 或同步仓库#

External contributors should fork the relevant Ultralytics repository, such as ultralytics/ultralytics, to their GitHub account.

拥有写权限的员工在创建分支前应同步 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

Link to this section创建功能分支#

创建一个分支,名称要清晰、具有描述性,反映所做的工作:

git checkout -b fix-issue-123
分支命名约定
  • fix-export-timeout 用于错误修复
  • add-training-metrics 用于功能开发
  • update-docs-training 用于文档更新
  • ci-link-check 用于自动化或基础设施

Link to this section进行变更#

遵循指南

遵循仓库现有的模式和风格

避免错误

避免新的警告、回归错误或不相关的变动

保持专注

将 PR 的范围限定在一个明确的成果上

Link to this section测试变更#

必须测试

在请求审查之前,运行与变更风险相匹配的检查:

pytest tests/

为新功能添加测试,并为错误修复添加回归测试。如果无法在本地运行相关检查,请在 PR 中说明原因并附上手动验证记录。

了解更多:Testing Requirements, Model Validation, CI Workflows

Link to this section提交变更#

提交时请使用简洁、描述性的信息:

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

Link to this section创建 Pull Request#

将你的分支 提交 PRmain 分支:

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

Link to this section签署 CLA#

合并前必须完成

外部贡献者必须签署 Contributor License Agreement (CLA),以便根据 AGPL-3.0 license 对贡献进行适当授权。

提交 PR 后,添加以下评论:

I have read the CLA Document and I sign the CLA

CLA 机器人将引导你完成整个流程。关于许可的更多详细信息,请参阅我们的 contributing guide

Link to this section处理审查反馈#

回复审查者意见,推送更新,如果范围发生变化,请保持 PR 描述处于最新状态。在请求重新审查之前,解决所有阻塞性的反馈。

Link to this sectionGoogle 风格 Docstrings 📝#

公共函数和类应使用 Google-style docstrings(在仓库要求的情况下)。保持文档字符串准确、简洁,并对未来的维护者有用。

Link to this section标准函数#

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

Link to this section命名返回#

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

Link to this section多个返回#

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.

Link to this section带有类型提示#

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

Link to this section单行文档字符串#

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

Link to this section代码标准 📐#

Link to this sectionPython 风格#

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

Link to this section代码质量#

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

Link to this section最佳实践#

避免重复

复用现有的辅助程序和模式

较小的变更

优先考虑针对性强的 PR,而非广泛的混合变更

简化

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

兼容性

保留公共 API 和用户工作流程

添加测试

覆盖新行为和回归测试

一致的格式

遵循存储库的格式化工具规范

Link to this section安全框架 🛡️#

Ultralytics 的工程实践应与公认的安全开发指南保持一致,包括 OWASP Secure Software Development LifecycleOWASP Application Security Verification Standard 以及 OWASP Top 10。在规划安全设计、审查、测试和修复工作时,团队应参考这些指南。

Link to this section资产管理 🗂️#

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

当创建、更改或弃用资产时:

  • 指定负责人和维护联系人。
  • 记录用途、环境、访问要求以及生命周期状态。
  • 审查访问权限和最小特权原则的执行情况。
  • 不要在代码、日志、截图和文档中包含机密信息和凭据。
  • 当所有权或行为发生变更时,更新运行手册、图表、清单或文档。
  • 弃用未使用的资产以降低安全、成本和维护风险。

Link to this section文档审查 📝#

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

文档审查人员应检查:

  • 角色名称、所有权和升级路径是否为最新。
  • 安全、合规和许可语言是否符合现行政策。
  • 链接、图表、命令和截图是否仍反映产品或工作流程的现状。
  • 新增或更改的流程是否包含明确的负责人和审查节奏。
  • 公共文档是否未泄露内部信息、机密、客户数据或敏感的操作细节。

Link to this section测试要求 ✅#

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

pytest tests/

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

对于模型行为的更改,请尽可能包含数据集、模型、命令、硬件以及更改前后的指标。对于文档的更改,请在本地构建文档,并包含针对布局更改的截图或预览链接。CI 详情请参阅 CI/Testing

Link to this section代码审查指南 👀#

Link to this section致贡献者#

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

Link to this section致审查者#

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

Link to this sectionGit 最佳实践 🌳#

Link to this section提交 (Commits)#

  • 使用现在时态:使用 "Add feature" 而非 "Added feature"。
  • 撰写清晰、描述性的信息。
  • 保持提交内容集中且逻辑性强。
  • 避免将仅格式化的变更与行为变更混在一起。

Link to this section分支 (Branches)#

  • 在创建分支前拉取最新的 main
  • 当分支滞后时,在最终提交前 Rebase 或合并 main
  • 合并后删除分支。

Link to this section报告 Bug 🐞#

通过 GitHub Issues 报告 Bug:

  1. 首先检查是否存在同类问题
  2. 提供 最小可复现示例
  3. 描述环境:操作系统、Python 版本、库版本、硬件(使用 yolo checks 进行诊断)
  4. 解释预期行为与实际行为,并附上错误信息

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

Link to this section许可协议 📜#

许多 Ultralytics 存储库使用 AGPL-3.0 许可证。如果你在自己的项目中使用了采用 AGPL 授权的 Ultralytics 代码,你的项目可能也需要根据 AGPL-3.0 进行开源。如果需要闭源或商业用途,请查看 企业许可证

Link to this section资源 📚#