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