开发工作流 💻
本指南介绍了 Ultralytics 的员工和贡献者如何在 Ultralytics 项目（包括YOLO 代码库）中规划、实施、审查、测试和合并更改。
该工作流刻意设计得简洁轻量：确保变更重点突出、便于审查、执行必要的检查，并保留足够的背景信息，以便团队成员日后能理解相关决策。
行为准则 🤝
所有投稿者必须遵守 行为准则. 在提交问题、PR、评审、内部讨论以及公开社区空间中，应保持尊重、清晰和专业。有关公开贡献的要求，请参阅 官方贡献指南.
协作节奏 🛰️
- 锚定日（周二/周三/周四）： 请利用这几天进行代码审查、设计讨论、调试工作，以及那些需要通过同步协作才能更有效决策的事项。
- 周一/周五： 优先处理深度工作、书面更新、PR 准备以及异步审查。若遇到关键阻碍，请将其推迟至下一个“锚定日”，届时将进行同步协调。
- 站立会议与评审： 将每日站会的时间限制在15分钟内。尽可能在“锚定日”安排设计和架构评审。
- 裁决记录： 请将重要决策记录在 PR 描述、问题、文档或运行手册中，以免聊天记录中的上下文丢失。
范围与所有权 🧭
此工作流适用于 Ultralytics 跨产品的工程工作， Ultralytics 平台、YOLO、基础设施、文档、自动化以及涉及安全敏感的系统。各个仓库可能会增加更严格的要求，但不应降低本页所述的基本要求。
每个工作项都应有明确的负责人：
- 作者： 实施更改，保持拉取请求处于最新状态，并提供验证依据。
- 审稿人： 确认正确性、可维护性、风险以及对文档的影响。
- 域名所有者： 审查影响特定领域的变更，例如模型行为、基础设施、安全性、隐私、许可或面向客户的工作流。
- Triage 所有者： 将收到的问题、事件、漏洞报告和维护任务分配给相应的负责人。
新工程任务应按影响程度、优先级、负责人和风险进行分类。涉及安全、生产、影响客户以及合规相关的工作，应明确指定负责人并制定后续处理流程，而非作为未分配的任务或聊天记录悬而未决。
拉取请求流程 🔄
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:#fff3cd1. 创建仓库分支或同步仓库
外部贡献者应 fork（派生） 相关的 Ultralytics 仓库，例如 ultralytics/ultralytics，到他们的 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. 进行修改
遵循该代码库现有的规范和风格
避免出现新的警告、回归问题或无关的代码变动
确保公关活动的目标聚焦于一个明确的成果
4. 测试您的更改
在请求审核之前，请先运行与您的变更风险相匹配的检查：
pytest tests/为新功能添加测试，并为 bug 修复添加回归测试。如果无法在本地运行相关检查，请在 PR 中说明原因，并附上手动验证说明。
5. 提交更改
提交 采用简洁、生动的表述：
git commit -m "Fix #123: Corrected calculation error"- 使用现在时（“添加功能”而非“已添加功能”）
- 如适用，请注明参考问题编号
- 请将主题行控制在72个字符以内
6. 创建拉取请求
提交 PR 从你的分支到 main:
- 描述更改内容的清晰标题
- 描述，涵盖目的、范围和验证
- 链接相关问题
- 负责人和所需审核人员已明确
- 请注意相关风险、兼容性问题或部署步骤
- 请附上界面变更的截图
- 测试在本地通过
7. 签署集体劳动协议
外部贡献者必须签署 贡献者许可协议 (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十大安全风险. 团队在规划安全设计、审查、测试和整改工作时，应参考这些资料。
资产管理 🗂️
工程资产应明确归属，并具备可靠的权威数据源。这包括代码仓库、服务、云资源、CI/CD 运行器、域名、数据集、模型构建产物、API 密钥、密钥、部署环境以及第三方集成。
在创建、变更或注销资产时：
- 指定一名负责人和一名维护联系人。
- 记录目的、环境、访问要求及生命周期状态。
- 审查访问权限和最小权限原则。
- 请勿在代码、日志、屏幕截图和文档中透露机密信息和凭据。
- 当所有权或行为发生变更时，请更新运行手册、图表、资产清单或文档。
- 淘汰闲置资产，以降低安全、成本和维护风险。
文档审查 📝
文档应与当前的角色、责任归属、工作流程及安全要求保持一致。当流程发生变更时，请在可行的情况下，在同一拉取请求中更新相关手册页面、公开文档、运行手册或 README 文件。
文档审核人员应检查：
- 角色名称、所有权和升级路径均为最新状态。
- 安全、合规和许可条款符合现行政策。
- 链接、图表、命令和屏幕截图仍反映了该产品或工作流程。
- 新流程或变更后的流程应明确指定负责人并设定审查周期。
- 公开文档不会披露仅限内部使用的信息、机密、客户数据或敏感的运营细节。
测试要求 ✅
所有 PR 都应包含与变更风险相匹配的验证：
pytest tests/
# When coverage is relevant
pytest --cov=ultralytics tests/对于模型行为的变更，请在可行的情况下提供数据集、模型、命令、硬件以及变更前后的指标。对于文档的变更，请在本地构建文档，并附上布局变更的截图或预览链接。参见 CI/测试 有关CI的详细信息。
代码审查指南 👀
致投稿者
- 请确保每个 PR 只针对一个功能、一个修复或一次文档更新。
- 请说明问题、解决方案、验证方法及风险。
- 及时回应反馈。
- 请将评审视为工作的一部分，而非个人评判。
- 如果范围发生变化，请更新 PR 描述。
致审稿人
- 请在一至两个工作日内审核，或尽快进行重定向。
- 检查新行为的测试和验证证据。
- 检查文档更新，以了解对用户可见的变更。
- 评估性能、兼容性、安全性、隐私性以及可维护性方面的影响。
- 验证相关持续集成检查是否通过。
- 提供建设性且具体的反馈。
- 区分阻碍性问题与建议。
Git 最佳实践 🌳
提交
- 请使用现在时：写“添加功能”，而不是“已添加功能”。
- 请撰写清晰、具体的信息。
- 请确保提交内容重点突出且逻辑清晰。
- 请避免将仅涉及格式调整的改动与行为变更混为一谈。
分支
- 拉取最新版本
main在创建分支之前。 - 重新基准化或合并
main在分支发生漂移时，在最终提交之前。 - 合并后删除分支。
报告错误 🐞
通过以下方式报告错误 GitHub 问题:
- 查看现有问题 首先
- 提供 最小可重现示例
- 描述环境: 操作系统、Python 、库版本、硬件（使用
yolo checks（用于诊断） - 解释预期行为与实际行为的差异 带有错误信息
有关常见问题及解决方案，请参阅我们的 故障排除指南.
许可证 📜
许多 Ultralytics 仓库使用 AGPL-3.0 许可. 如果您在项目中使用了采用 AGPL 许可的 Ultralytics 代码，您的项目可能也需要根据AGPL-3.0开源。如果您需要闭源或进行商业用途，请查阅 企业许可证.