开发工作流 💻#
本指南介绍 Ultralytics 员工和贡献者如何在 Ultralytics 项目（包括 YOLO 及相关仓库）中规划、实现、审查、测试和合并变更。
该工作流有意保持轻量：聚焦变更范围，让审查变得容易，运行正确的检查，并留下足够的上下文，方便队友日后理解相关决策。
行为准则 🤝#
所有贡献者都必须遵守 行为准则。在 issue、PR、审查、内部讨论和公开社区空间中，都应保持尊重、清晰和专业。有关公开贡献要求，请参阅官方贡献指南。
协作节奏 🛰️#
- 协作日（周二/周三/周四）： 将这些时间用于代码审查、设计讨论、调试会话，以及适合同步协作的决策。
- 周一/周五： 优先进行深度工作、书面更新、PR 准备和异步审查。需要同步达成一致时，将关键阻塞问题移到下一个协作日。
- 站会与审查： 将站会控制在 15 分钟内。尽可能在协作日安排设计和架构审查。
- 决策记录： 将重要决策记录在 PR 描述、issue、文档或运行手册中，避免上下文在聊天中消失。
范围与所有权 🧭#
此工作流适用于 Ultralytics 在产品、Ultralytics Platform、YOLO、基础设施、文档、自动化和安全敏感系统方面的工程工作。各个仓库可以增加更严格的要求，但不应降低本页面规定的基线要求。
每个工作项都应有明确的负责人：
- 作者： 实施变更、保持 PR 为最新状态，并提供验证证据。
- 审查者： 确认正确性、可维护性、风险和文档影响。
- 领域负责人： 审查影响专业领域的变更，例如模型行为、基础设施、安全、隐私、许可或面向客户的工作流。
- 分诊负责人： 将新收到的 issue、事件、漏洞报告和维护工作分配给合适的负责人。
新的工程工作应根据影响、优先级、负责人和风险进行分诊。安全、生产、影响客户以及合规相关的工作应明确负责人和后续处理路径，不应一直作为未分配的 issue 或聊天线程存在。
拉取请求流程 🔄#
flowchart TD
A[Fork or Sync Repository]:::start --> B[Create Feature Branch]:::proc
B --> C[Make Changes]:::proc
C --> D[Run Tests Locally]:::proc
D --> E[Commit Changes]:::proc
E --> F[Create Pull Request]:::proc
F --> G[Sign CLA]:::proc
G --> H{Review}:::decide
H -->|Changes Requested| I[Address Feedback]:::proc
I --> H
H -->|Approved| J[Merge!]:::out
classDef start fill:#4CAF50,color:#fff
classDef proc fill:#2196F3,color:#fff
classDef decide fill:#FF9800,color:#fff
classDef out fill:#9C27B0,color:#fff1. Fork 或同步仓库#
外部贡献者应将相关的 Ultralytics 仓库（例如 ultralytics/ultralytics）fork 到自己的 GitHub 账户。
拥有写入权限的员工应在创建分支前同步 main：
# External contributors
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
# Employees with write access
git checkout main
git pull origin main2. 创建功能分支#
创建分支时，应使用清晰且具有描述性的名称来反映工作内容：
git checkout -b fix-issue-123fix-export-timeout用于错误修复add-training-metrics用于功能开发update-docs-training用于文档ci-link-check用于自动化或基础设施
3. 进行变更#
遵循仓库现有的模式和风格
避免引入新的警告、回归问题或无关变更
将 PR 范围限定为一个明确的结果
4. 测试变更#
在请求审查前，运行与变更风险相匹配的检查：
pytest tests/为新功能添加测试，并为错误修复添加回归测试。如果相关检查无法在本地运行，请在 PR 中说明原因，并附上手动验证说明。
5. 提交变更#
使用简洁且具有描述性的消息进行 提交：
git commit -m "Fix #123: Corrected calculation error"- 使用现在时（“Add feature”，而不是“Added feature”）
- 适用时引用 issue 编号
- 将主题行控制在 72 个字符以内
6. 创建拉取请求#
将分支中的内容提交为 PR到 main：
- 清晰描述变更内容的标题
- 涵盖目的、范围和验证情况的描述
- 关联相关 issue
- 明确负责人和所需审查者
- 注明风险、兼容性问题或发布步骤
- 为 UI 变更添加屏幕截图
- 本地测试通过
7. 签署 CLA#
外部贡献者必须签署贡献者许可协议（CLA），以便根据 AGPL-3.0 许可证正确授予贡献内容的许可。
提交 PR 后，添加以下评论：
I have read the CLA Document and I sign the CLA
CLA 机器人会引导你完成流程。有关许可的更多详情，请参阅我们的贡献指南。
8. 处理审查反馈#
回复审查者的评论，推送更新；如果范围发生变化，及时更新 PR 描述。在请求重新审查前，解决所有阻塞性反馈。
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，而不是手动处理路径字符串 | 使用现代化的跨平台路径 |
| 类型提示 | 在能够提升清晰度时使用 | 公共 API、复杂结构和返回数据 |
| 函数 | 保持聚焦且可测试 | 将复杂逻辑拆分为命名明确的辅助函数 |
代码质量#
- 没有未使用的导入或变量
- 命名一致（
lowercase_with_underscores） - 使用清晰的变量名；除循环计数器外，避免使用单字母变量名
最佳实践#
复用现有的辅助函数和模式
优先提交专注明确的 PR，而不是范围广泛且混杂的变更
在有助于提高清晰度时移除复杂性
保留公共 API 和用户工作流
覆盖新增行为和回归问题
遵循仓库的格式化工具
安全框架 🛡️#
Ultralytics 的工程实践应与公认的安全开发指南保持一致，包括 OWASP 安全软件开发生命周期、OWASP 应用安全验证标准和 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 最佳实践 🌳#
提交#
- 使用现在时态：使用 “Add feature”，而不是 “Added feature”。
- 编写清晰、具有描述性的消息。
- 让提交保持专注且逻辑清晰。
- 避免将仅格式变更与行为变更混在一起。
分支#
- 创建分支前拉取最新的
main。 - 当分支与主线发生偏离时，在最终提交前对
main执行变基或合并。 - 合并后删除分支。
报告错误 🐞#
通过 GitHub Issues 报告错误：
- 先检查现有问题
- 提供 最小可复现示例
- 描述环境：操作系统、Python 版本、库版本、硬件（使用
yolo checks进行诊断） - 结合错误消息说明预期行为与实际行为
有关常见问题和解决方案，请参阅我们的故障排除指南。
许可 📜#
许多 Ultralytics 仓库使用 AGPL-3.0 许可证。如果你在项目中使用 AGPL 许可的 Ultralytics 代码，你的项目可能也需要根据 AGPL-3.0 开源。如果你需要闭源或商业用途，请查看 企业许可证。
资源 📚#
- 官方贡献指南 - 完整的贡献指南
- CI/Testing - 持续集成详情
- 文档 - 编写和维护文档
- 行为准则 - 社区规范
- CLA 说明 - 贡献者许可协议指南
- 最小可复现示例 - 错误报告示例
- Ultralytics 博客 - 最新动态和教程
- 社区活动 - 网络研讨会和会议