Link to this section为 Ultralytics 开源项目做出贡献#

欢迎！我们非常高兴你能考虑为我们的 Ultralytics 开源项目做出贡献。你的参与不仅有助于提升我们代码库的质量，也让整个计算机视觉社区受益。本指南提供了清晰的指导原则和最佳实践，帮助你开始这一过程。

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

Link to this section🤝 行为准则#

为了确保每个人都能感受到友好和包容的氛围，所有贡献者必须遵守我们的 Code of Conduct。尊重、友善和专业精神是我们社区的核心。

Link to this section🚀 通过 Pull Requests 贡献#

我们非常感谢通过 Pull Requests (PRs) 形式做出的贡献。为了让审查过程尽可能顺畅，请遵循以下步骤：

Fork 代码库： 首先，将相关的 Ultralytics 代码库（例如 ultralytics/ultralytics）Fork 到你的 GitHub 账户中。
创建分支： 在你 Fork 的代码库中创建一个新分支，并使用清晰、描述性的名称来反映你的更改（例如 fix-issue-123，add-feature-xyz）。
做出更改： 实现你的改进或修复。请确保你的代码符合项目的风格指南，并且不会引入新的错误或警告。
测试你的更改： 在提交之前，请在本地测试你的更改，以确认它们按预期工作且不会引起回归问题。如果你引入了新功能，请添加相应的测试。
提交更改： 使用简洁且具有描述性的提交信息来提交你的更改。如果你的更改解决了某个特定的问题，请包含问题编号（例如 Fix #123: Corrected calculation error.）。
创建 Pull Request： 从你的分支向原始 Ultralytics 代码库的 main 分支提交 PR。请提供清晰的标题和详细的描述，解释你更改的目的和范围。

Link to this section📝 签署 CLA#

在合并你的 pull request 之前，你必须签署我们的 Contributor License Agreement (CLA)。这项法律协议确保你的贡献获得了适当的许可，从而使该项目能够继续在 AGPL-3.0 license 下分发。

提交 PR 后，CLA 机器人会引导你完成签署流程。要签署 CLA，只需在你的 PR 中添加一条评论，内容如下：

I have read the CLA Document and I sign the CLA

Link to this section✍️ Google 风格文档字符串#

添加新函数或类时，请包含 Google 风格文档字符串，以获得清晰、标准化的文档。始终将输入和输出的 types 用括号括起来（例如 (bool)，(np.ndarray)）。

文档字符串示例

此示例展示了标准的 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

Link to this section✅ GitHub Actions CI 测试#

所有的 pull request 在合并前都必须通过 GitHub Actions Continuous Integration (CI) 测试。这些测试包括代码检查、单元测试以及其他确保你的更改符合项目质量标准的检测。请查看 CI 输出并处理出现的任何问题。

Link to this section✨ 代码贡献最佳实践#

向 Ultralytics 项目贡献代码时，请记住这些最佳实践：

避免代码重复： 尽可能重用现有代码，并减少不必要的参数。
进行小而集中的更改： 专注于有针对性的修改，而不是大规模更改。
尽可能简化： 寻找机会简化代码或移除不必要的部分。
考虑兼容性： 在进行更改之前，请考虑它们是否会破坏现有的 Ultralytics 使用代码。
使用一致的格式： 诸如 Ruff Formatter 之类的工具可以帮助保持风格一致性。
添加适当的测试： 为新功能包含 tests，以确保它们按预期工作。

Link to this section👀 审查 Pull Requests#

审查 Pull Requests 是另一种有价值的贡献方式。在审查 PR 时：

检查单元测试： 验证 PR 是否包含针对新功能或更改的测试。
审核文档更新： 确保已更新 documentation 以反映所做的更改。
评估性能影响： 考虑更改可能如何影响 performance。
验证 CI 测试： 确认所有 Continuous Integration tests 均已通过。
提供建设性反馈： 针对任何问题或疑虑提供具体、清晰的反馈。
认可努力： 肯定作者的工作，以保持积极的协作氛围。

Link to this section🐞 报告 Bug#

我们高度重视 Bug 报告，因为它们帮助我们提升项目的质量和可靠性。通过 GitHub Issues 报告 Bug 时：

检查现有问题： 先搜索一下该 Bug 是否已被报告过。
提供一个 Minimum Reproducible Example： 创建一个小的、自包含的代码片段，能够持续复现该问题。这对高效调试至关重要。
描述环境： 指定你的操作系统、Python 版本、相关库版本（例如 torch，ultralytics）以及硬件（CPU/GPU）。
解释期望行为与实际行为： 明确说明你预期的结果以及实际发生的结果。包含任何错误信息或追踪信息。

Link to this section📜 许可证#

Ultralytics 的代码库使用 GNU Affero 通用公共许可证 v3.0 (AGPL-3.0)。该许可证促进了软件开发中的开放性、透明度和协作改进。它确保所有用户都有权使用、修改和共享软件，从而培育了一个强大的协作与创新社区。

我们鼓励所有贡献者熟悉 AGPL-3.0 许可证的条款，以便高效且合乎伦理地为 Ultralytics 开源社区做出贡献。

Link to this section🌍 在 AGPL-3.0 下开源你的 YOLO 项目#

在你的项目中使用 Ultralytics YOLO 模型或代码？AGPL-3.0 许可证要求你的整个衍生作品也必须在 AGPL-3.0 下开源。这确保了在开源基础上构建的修改内容和更大规模的项目能够保持开放。

Link to this section为什么 AGPL-3.0 合规很重要#

保持软件开放： 确保改进和衍生作品能够造福社区。
法律要求： 使用 AGPL-3.0 许可的代码意味着你的项目受其条款约束。
促进协作： 鼓励分享与透明。

如果你不想开源你的项目，请考虑获取企业许可证。

Link to this section如何遵守 AGPL-3.0#

合规意味着将你项目的完整对应源代码在 AGPL-3.0 许可证下公开。

选择你的起点：
- Fork Ultralytics YOLO： 如果是在此基础上深度构建，请直接 Fork Ultralytics YOLO 代码库。
- 使用 Ultralytics 模板： 从 Ultralytics 模板代码库开始，获得一个集成了 YOLO 的干净、模块化的设置。
为你的项目授权：
- Add a LICENSE file containing the full text of the AGPL-3.0 license.
- 在每个源代码文件的顶部添加一条注明许可证的通知。
发布你的源代码：
- 使你的整个项目的源代码可公开访问（例如，在 GitHub 上）。这包括：
  - 结合了 YOLO 模型或代码的完整大型应用程序或系统。
  - 对原始 Ultralytics YOLO 代码所做的任何修改。
  - 用于训练、验证和推理的脚本。
  - 如果经过修改或微调，请提供模型权重。
  - Configuration files，环境设置 (requirements.txt, Dockerfiles)。
  - 如果属于网络应用的一部分，请提供后端和前端代码。
  - 你修改过的任何第三方库。
  - 如果运行/再训练所需且可重新分发，请提供训练数据。
清晰记录：
- 更新你的 README.md，声明该项目在 AGPL-3.0 下许可。
- 包含有关如何从源代码设置、构建和运行你的项目的清晰说明。
- 正确标注 Ultralytics YOLO，并链接回原始代码库。例如：
```
This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.
```

Link to this section示例代码库结构#

请参考 Ultralytics 模板代码库获取实用结构示例：

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

通过遵循这些指导原则，你可以确保遵守 AGPL-3.0，从而支持使 Ultralytics YOLO 等强大工具成为可能的开源生态系统。

Link to this section结论#

感谢你对参与 Ultralytics 开源 YOLO 项目的兴趣。你的参与对于塑造我们软件的未来以及构建一个充满活力、创新和协作的社区至关重要。无论你是增强代码、报告 Bug 还是建议新功能，你的贡献都价值连城。

我们期待看到你的想法变为现实，并感谢你致力于推动目标检测技术的发展。让我们一起在这个激动人心的开源之旅中继续成长和创新。

Link to this section常见问题解答#

Link to this section我为什么要为 Ultralytics YOLO 开源代码库做出贡献？#

为 Ultralytics YOLO 开源代码库做出贡献可以改进软件，使其对整个社区更加健壮且功能丰富。贡献可以包括代码增强、Bug 修复、文档改进和新功能实现。此外，做出贡献还可以让你与其他优秀的开发人员和领域专家协作，从而提升你自己的技能和声誉。有关如何开始的详情，请参阅通过 Pull Requests 贡献部分。

Link to this section我该如何为 Ultralytics YOLO 签署贡献者许可协议 (CLA)？#

要签署贡献者许可协议 (CLA)，请在提交 Pull Request 后遵循 CLA 机器人提供的说明。此过程确保你的贡献在 AGPL-3.0 许可证下得到正确授权，从而维护开源项目的法律完整性。在你的 Pull Request 中添加一条评论，内容如下：

I have read the CLA Document and I sign the CLA

有关更多信息，请参阅签署 CLA 部分。

Link to this section什么是 Google 风格文档字符串，为什么 Ultralytics YOLO 贡献需要它们？#

Google 风格文档字符串为函数和类提供了清晰、简洁的文档，提高了代码的可读性和可维护性。这些文档字符串通过特定的格式规则概述了函数的功能、参数和返回值。当为 Ultralytics YOLO 做出贡献时，遵循 Google 风格文档字符串可确保你的添加内容文档齐全且易于理解。有关示例和指南，请访问Google 风格文档字符串部分。

Link to this section我该如何确保我的更改通过 GitHub Actions CI 测试？#

在你的 pull request 被合并之前，它必须通过所有的 GitHub Actions Continuous Integration (CI) 测试。这些测试包括代码检查（linting）、单元测试以及其他确保代码符合项目质量标准的检查。请查看 CI 输出并修复任何问题。有关 CI 流程和故障排除技巧的详细信息，请参阅 GitHub Actions CI Tests 部分。

Link to this section我该如何在 Ultralytics YOLO 存储库中报告错误？#

若要报告 bug，请在 bug 报告中提供一个清晰简洁的 Minimum Reproducible Example。这有助于开发者快速识别并修复问题。请确保你的示例尽可能精简，但足以复现问题。有关报告 bug 的更详细步骤，请参阅 Reporting Bugs 部分。

Link to this section如果我在自己的项目中使用 Ultralytics YOLO，AGPL-3.0 许可证意味着什么？#

如果你在项目中使用了 Ultralytics YOLO 代码或模型（基于 AGPL-3.0 许可），AGPL-3.0 许可证要求你的整个项目（衍生作品）也必须在 AGPL-3.0 下获得许可，并且其完整的源代码必须公开。这确保了软件的开源性质在其衍生作品中得到保留。如果你无法满足这些要求，你需要获取一份 Enterprise License。详细信息请参阅 Open-Sourcing Your Project 部分。

贡献者

GLglenn-jocher²³ RIRizwanMunawar³ RAraimbekovm¹ PDpderrenger¹ Y-Y-T-G¹ WIWillieMaddox¹ LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

已创建 2023年11月12日已更新 3天前