开发工作流 💻
本指南涵盖了 Ultralytics 员工和贡献者如何在 Ultralytics 项目（包括 YOLO 及相关存储库）中规划、实现、审查、测试和合并更改。
该工作流旨在保持轻量化：确保更改重点突出，使审查变得容易，运行正确的检查，并留下足够的背景信息供团队成员后续理解决策过程。
行为准则 🤝
所有贡献者必须遵守行为准则。在 Issue、PR、审查、内部讨论和公共社区空间中，我们期望大家保持尊重、清晰和专业。有关公共贡献的要求，请参阅官方贡献指南。
协作节奏 🛰️
- 锚点日（周二/周三/周四）： 利用这些时间进行代码审查、设计讨论、调试会话以及需要同步协作的决策。
- 周一/周五： 优先进行深度工作、书面更新、PR 准备和异步审查。当需要同步对齐时，将关键阻碍事项移至下一个锚点日。
- 每日站会与审查： 将站会时间限制在 15 分钟内。尽可能在锚点日安排设计和架构审查。
- 决策记录： 将重要决策记录在 PR 描述、Issue、文档或手册中，以免背景信息在聊天中丢失。
范围与所有权 🧭
此工作流适用于 Ultralytics 在产品、Ultralytics Platform、YOLO、基础设施、文档、自动化和安全敏感系统方面的工程工作。各个存储库可能会添加更严格的要求，但不应削弱本页面中的基准期望。
每项工作任务都应有明确的负责人：
- 作者： 实现更改，保持 PR 更新，并提供验证证据。
- 审查者： 确认正确性、可维护性、风险以及对文档的影响。
- 领域所有者： 审查影响特定领域（如模型行为、基础设施、安全、隐私、许可或面向客户的工作流）的更改。
- 分流所有者： 将传入的 Issue、事件、漏洞报告和维护工作分配给正确的负责人。
新的工程工作应根据影响、优先级、所有权和风险进行分流。涉及安全、生产、客户影响和合规性的工作应有明确的负责人和跟进路径，而不是作为未分配的 Issue 或聊天记录。
Pull 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:#fff3cdFork 或同步存储库
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创建功能分支
创建分支，名称应清晰且具有描述性，反映所做的工作：
git checkout -b fix-issue-123fix-export-timeout用于错误修复add-training-metrics用于新功能update-docs-training用于文档ci-link-check用于自动化或基础设施
进行更改
遵循存储库现有的模式和风格
避免出现新的警告、回归或不相关的变动
将 PR 范围限制在一个清晰的结果上
测试更改
在请求审查之前，运行与更改风险相匹配的检查：
pytest tests/为新功能添加测试，并为错误修复添加回归测试。如果无法在本地运行相关的检查，请在 PR 中解释原因并包含手动验证说明。
提交更改
使用简洁、描述性的信息进行提交：
git commit -m "Fix #123: Corrected calculation error"- 使用现在时（“Add feature” 而非 “Added feature”）
- 适用时引用 Issue 编号
- 主题行保持在 72 个字符以内
创建 Pull Request
将你的分支 提交 PR 到 main：
- 清晰的标题描述更改
- 描述涵盖目的、范围和验证
- 链接相关的 Issue
- 负责人和必要的审查者明确
- 注意风险、兼容性问题或发布步骤
- UI 更改包含截图
- 本地测试已通过
签署 CLA
外部贡献者必须签署贡献者许可协议 (CLA)，以便贡献内容能根据 AGPL-3.0 许可证获得适当许可。
提交 PR 后，添加以下评论：
I have read the CLA Document and I sign the CLA
CLA 机器人将引导你完成整个过程。有关许可的更多详细信息，请参阅我们的贡献指南。
处理审查反馈
回复审查者评论，推送更新，如果范围发生变化，请保持 PR 描述为最新。在请求重新审查之前，解决所有阻碍性的反馈。
Google 风格 Docstring 📝
公共函数和类应在存储库要求的地方使用 Google 风格 docstring。保持 docstring 准确、简洁，并对未来的维护者有用。
标准函数
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单行 Docstring
def example_small_function(arg1: int, arg2: int = 4) -> bool:
"""Example function with a single-line docstring."""
return arg1 == arg2代码标准 📐
Python 风格
| 标准 | 要求 | 示例 |
|---|---|---|
| 行宽 | 遵循存储库配置，通常为 120 个字符 | 保持代码行可读且易于扫描 |
| Docstring | Google 风格 | 在有帮助的地方使用类型和示例 |
| 导入 | 优先使用 pathlib 而不是手动处理路径字符串 | 现代、跨平台的路径 |
| 类型提示 | 在能提高清晰度时使用 | 公共 API、复杂结构、返回数据 |
| 函数 | 保持专注且可测试 | 将复杂的逻辑拆分为命名辅助函数 |
代码质量
- 没有未使用的导入或变量
- 命名一致 (
lowercase_with_underscores) - 变量名清晰；避免使用单个字母，循环计数器除外
最佳实践
重用现有的辅助工具和模式
优先考虑专注的 PR，而不是宽泛的混合变更
当复杂性降低时，移除不必要的复杂度以提升清晰度
保留公共 API 和用户工作流程
覆盖新的行为和回归问题
遵循仓库的格式化工具
安全框架 🛡️
Ultralytics 的工程实践应与公认的安全开发指导保持一致，包括 OWASP Secure Software Development Lifecycle、OWASP Application Security Verification Standard 和 OWASP Top 10。团队在规划安全设计、评审、测试和修复工作时应参考这些指南。
资产管理 🗂️
工程资产应有明确的负责人和可靠的事实来源。这包括仓库、服务、云资源、CI/CD 运行器、域名、数据集、模型工件、API 密钥、凭据、部署环境和第三方集成。
在创建、更改或退役资产时：
- 指派一名负责人和维护联系人。
- 记录其目的、环境、访问要求和生命周期状态。
- 审查访问权限和最小特权原则。
- 不要将密钥和凭据留在代码、日志、截图和文档中。
- 当所有权或行为发生变化时，更新运行手册、图表、清单或文档。
- 退役未使用的资产以降低安全、成本和维护风险。
文档审查 📝
文档应与当前的角色、权责、工作流程和安全预期保持一致。当流程发生变化时，应在同一个 PR 中尽可能更新相关的手册页面、公开文档、运行手册或 README。
文档审查人员应检查：
- 角色名称、权责和升级路径是否为最新。
- 安全、合规和许可条款是否符合当前政策。
- 链接、图表、命令和截图是否仍反映当前的产品或工作流程。
- 新增或变更的流程是否包含明确的负责人和审查周期。
- 公开文档是否未泄露仅限内部的信息、密钥、客户数据或敏感的运营细节。
测试要求 ✅
所有 PR 都应包含与变更风险相匹配的验证：
pytest tests/
# When coverage is relevant
pytest --cov=ultralytics tests/对于模型行为的变更，请尽可能包含数据集、模型、命令、硬件以及变更前后的指标。对于文档变更，请在本地构建文档，并为布局变更提供截图或预览链接。有关 CI 的详细信息，请参阅 CI/Testing。
代码审查指南 👀
针对贡献者
- 保持 PR 专注于一个功能、修复或文档更新。
- 解释问题、解决方案、验证方式和潜在风险。
- 及时回应反馈。
- 将审查视为工作的一部分，而非针对个人的评价。
- 如果范围发生变化，请更新 PR 描述。
针对审查人员
- 在一到两个工作日内完成审查或快速重定向。
- 检查针对新行为的测试和验证证据。
- 审查文档更新以了解用户可见的变更。
- 评估对性能、兼容性、安全性、隐私和可维护性的影响。
- 验证相关的 CI 检查是否通过。
- 提供建设性且具体的反馈。
- 区分阻塞性问题和改进建议。
Git 最佳实践 🌳
提交 (Commits)
- 使用现在时态：用 "Add feature" 而不是 "Added feature"。
- 编写清晰、具有描述性的信息。
- 保持提交内容专注且逻辑严密。
- 避免将仅涉及格式化的改动与行为变更混在一起。
分支 (Branches)
- 在创建分支前拉取最新的
main。 - 当分支滞后时，在最终提交前 Rebase 或合并
main。 - 合并后删除分支。
报告 Bug 🐞
通过 GitHub Issues 报告 Bug：
- 首先检查已有的 issue
- 提供 最小可复现示例
- 描述环境：操作系统、Python 版本、库版本、硬件（使用
yolo checks进行诊断） - 解释预期行为与实际行为并提供错误消息
常见问题及解决方案，请参阅我们的 故障排除指南。
许可证 📜
许多 Ultralytics 仓库使用 AGPL-3.0 许可证。如果您在项目中使用基于 AGPL 许可的 Ultralytics 代码，您的项目也可能需要根据 AGPL-3.0 进行开源。如果您需要闭源或商业用途，请查阅 企业许可。
资源 📚
- 官方贡献指南 - 完整的贡献准则
- CI/Testing - 持续集成详细信息
- 文档 - 文档编写与维护
- 行为准则 - 社区标准
- CLA 说明 - 贡献者许可协议指导
- 最小可复现示例 - Bug 报告示例
- Ultralytics 博客 - 最新更新与教程
- 社区活动 - 网络研讨会与会议