跳到内容

开发工作流程 💻

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

行为准则 🤝

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

Pull Request 流程 🔄

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. 提交更改

使用简洁、描述性的消息进行 Commit：

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

在处理特定问题时，请包含问题编号。

6. 创建 Pull Request

提交 PR 从您的分支到 main:

  • 清晰的标题，描述更改
  • 详细描述目的和范围
  • 链接相关问题
  • 包含 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
  • 类型提示：为清晰起见，请使用
  • 函数：保持简短和专注（理想情况下少于 50 行）

代码质量

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

最佳实践

  • 避免重复：重用现有代码
  • 小改动：专注于修改，避免大规模更改
  • 简化：寻找简化的机会
  • 兼容性：避免破坏现有代码
  • 一致的格式：使用 Ruff Formatter
  • 添加测试：为新功能添加测试

测试要求 ✅

所有 PR 必须通过 CI 测试：

# Run tests locally
pytest tests/

# With coverage
pytest --cov=ultralytics tests/

有关 CI 详细信息，请参阅 CI/测试。

代码审核指南 👀

贡献者指南

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

审核者指南

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

Git 最佳实践 🌳

提交

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

分支

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

报告 Bug 🐞

通过 GitHub Issues 报告错误：

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

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

许可证 📜

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

资源 📚



📅 1 个月前创建 ✏️ 9 天前更新
glenn-jocher