跳至内容

开发工作流程 💻

本指南涵盖了为 Ultralytics项目的开发流程，包括YOLO11 和相关资源库。

行为准则 🤝

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

拉取请求流程 🔄

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.分叉存储库

将相关的Ultralytics 软件仓库（如ultralyticsultralyticsultralytics）分叉到你的 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 进行错误修复
  • add-feature-xyz 新功能
  • update-docs-training 用于文档

3.进行更改

  • 遵循指导原则

    遵守项目风格指南

  • 避免错误

    不要引入新的警告

  • 保持专注

    尽量减少改动，有的放矢

4.测试更改

需要测试

提交前在本地进行测试：

pytest tests/

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

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

5.承诺您的更改

以简洁、描述性的信息进行承诺：

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

承诺信息最佳做法

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

6.创建拉取请求

提交公关 从您的分支到 main:

  • 标题明确，说明更改内容
  • 目的和范围的详细说明
  • 链接相关问题
  • 包含用户界面更改的截图
  • 本地通过的测试

7.签署 CLA

合并前需要

您必须签署我们的贡献者许可协议 (CLA)，以确保您的贡献在AGPL-3.0 许可下得到正确授权。

提交 PR 后，请添加此注释：

I have read the CLA Document and I sign the CLA

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

8.处理审查反馈

回复审核员的评论并推送更新。

Google文档字符串 📝

所有函数和类都需要Google docstrings，并在括号中注明类型。

标准功能

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 lines ideally 保持重点突出和可测试性

代码质量

质量检查表

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

最佳做法

  • 避免重复

    重复使用现有代码 - DRY 原则

  • 较小的变化

    集中修改 > 大规模修改

  • 简化

    寻找简化机会

  • 兼容性

    避免破坏现有代码

  • 添加测试

    包括新功能测试

  • 格式一致

    使用Ruff 格式

测试要求 ✅

所有 PR 必须通过 CI 测试：

# Run tests locally
pytest tests/

# With coverage
pytest --cov=ultralytics tests/

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

代码审查指南 👀

供稿人

  • 让 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 下开源。如果您不想开源，请获取企业许可证。

资源 📚



📅创建于 4 天前 ✏️已更新 4 天前
翔宇