跳到内容

开发工作流程 💻

本指南涵盖了为 Ultralytics 项目（包括 YOLO11 和相关存储库）做出贡献的开发流程。

行为准则 🤝

所有贡献者都必须遵守我们的行为准则。尊重、友善和专业精神是我们社区的核心。有关详细的贡献指南，请参阅官方贡献指南。

协作节奏 🛰️

  • 固定工作日（周二/周三/周四）：对于通勤距离内的团队成员，代码审查、设计讨论和调试默认采用面对面形式——优先使用白板而非冗长讨论，以降低沟通延迟。
  • 周一/周五：优先处理深度工作和异步更新；若需同步协调，将关键阻碍事项移至下一个锚定日处理。
  • 站会与评审：站会时长控制在15分钟内；设计/架构评审安排在锚定日进行，以最大化带宽利用率。

Pull Request 流程 🔄

flowchart TD
    A[Fork 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

1. Fork 代码仓库

Fork 相关的 Ultralytics 存储库（例如，ultralytics/ultralytics）到您的 GitHub 帐户。

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics

2. 创建特性分支

创建一个分支，并使用清晰、描述性的名称：

git checkout -b fix-issue-123

分支命名规范

  • fix-issue-123 用于修复 Bug
  • add-feature-xyz 用于新增功能
  • update-docs-training 用于更新文档

3. 做出您的更改

  • 遵循指南

    遵守项目风格指南

  • 避免错误

    不要引入新的警告

  • 保持专注

    尽量减少更改并使其有针对性

4. 测试您的更改

需要进行测试

提交前请在本地进行测试：

pytest tests/

为新功能添加测试，以防止出现回归问题。

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

5. 提交您的更改

使用简洁、描述性的消息提交：

git commit -m "Fix #123: Corrected calculation error"

承诺信息最佳做法

  • 使用现在时态（"添加功能 "而不是 "增加功能"）。
  • 如适用，请参考问题编号
  • 主题行不要超过 72 个字符

6. 创建 Pull Request

提交 PR 从您的分支到 main:

  • 清晰的标题，描述更改内容
  • 对目的和范围的详细描述
  • 链接相关 issue
  • 包含 UI 更改的屏幕截图
  • 本地测试通过

7. 签署 CLA

合并前需要

您必须签署我们的贡献者许可协议 (CLA)，以确保贡献已根据 AGPL-3.0 license 正确获得许可。

提交 PR 后，请添加此评论：

I have read the CLA Document and I sign the CLA

CLA 机器人将指导您完成整个过程。有关许可的更多详细信息，请参阅我们的贡献指南。

8. 解决审查反馈

回复审阅者的评论并推送更新。

Google 风格文档字符串 📝

所有函数和类都需要 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 个字符 保持行可读和可扫描
文档字符串 Google 风格 括号中的类型
导入 pathlib 超过 os 现代、跨平台路径
类型提示 在有益时使用 改进 IDE 支持
函数 <50 lines ideally 保持专注和可测试性

代码质量

质量检查清单

  • 没有未使用的导入或变量
  • 一致的命名 (lowercase_with_underscores)
  • 清晰的变量名（避免使用单个字母，循环计数器除外）
  • 使用 f-strings 进行字符串格式化
  • 仅为复杂的逻辑添加注释
  • Ruff Formatter 为了保持一致性

最佳实践

  • 避免重复

    重用现有代码 - DRY 原则

  • 较小的更改

    专注的修改 > 大规模的更改

  • 简化

    寻找简化的机会

  • 兼容性

    避免破坏现有代码

  • 添加测试

    为新功能添加测试

  • 一致的格式

    使用 Ruff Formatter

测试要求 ✅

所有PR必须通过CI测试：

# Run tests locally
pytest tests/

# With coverage
pytest --cov=ultralytics tests/

有关CI的详细信息，请参阅CI/Testing。

代码审查指南 👀

贡献者

  • 保持PR专注于单个功能/修复
  • 及时回复反馈
  • 不要将反馈视为针对个人
  • 如果范围发生变化，请更新PR描述

审查者

  • 在1-2个工作日内完成审核
  • 检查新功能的单元测试
  • 审查文档更新
  • 评估性能影响
  • 验证CI测试是否通过
  • 提供建设性的、具体的反馈
  • 认可作者的努力

Git 最佳实践 🌳

提交

  • 使用现在时："添加功能"而不是"已添加功能"
  • 清晰、描述性的信息
  • 专注、符合逻辑的提交

分支

  • 拉取最新版本 main 在创建分支之前
  • 基于...变基 main 在最终提交之前
  • 合并后删除分支

问题报告 🐞

通过GitHub Issues报告错误：

  1. 首先检查现有问题
  2. 提供最小可复现示例
  3. 描述环境操作系统、python版本、库版本、硬件（用于诊断） yolo checks 用于诊断）
  4. 说明预期行为与实际行为，并附上错误信息

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

许可 📜

Ultralytics 使用 AGPL-3.0。如果在您的项目中使用 Ultralytics 代码，则您的整个项目必须在 AGPL-3.0 下开源。如果您不想开源，请获得 企业许可证。

资源 📚



📅创建于21天前 ✏️更新于21天前
glenn-jocher