为 Ultralytics 开源项目做出贡献#

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

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

🤝 行为准则#

为了确保为所有人提供一个热情且包容的环境，所有贡献者都必须遵守我们的行为准则。尊重、友好和专业是我们社区的核心。

🚀 通过 Pull Requests 贡献#

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

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

📝 签署 CLA#

在我们合并你的拉取请求之前，你必须签署我们的贡献者许可协议 (CLA)。这一法律协议可确保你的贡献获得适当的许可，从而使项目能够继续在 AGPL-3.0 许可证下进行分发。

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

I have read the CLA Document and I sign the CLA

✍️ 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

✅ GitHub Actions CI 测试#

所有拉取请求在合并之前必须通过 GitHub Actions 持续集成 (CI) 测试。这些测试包括代码检查、单元测试和其他检查，以确保你的更改符合项目的质量标准。请查看 CI 输出并解决出现的任何问题。

✨ 代码贡献最佳实践#

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

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

👀 审查 Pull Requests#

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

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

🐞 报告 Bug#

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

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

📜 许可证#

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

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

🌍 在 AGPL-3.0 下开源你的 YOLO 项目#

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

为什么 AGPL-3.0 合规很重要#

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

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

如何遵守 AGPL-3.0#

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

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

示例代码库结构#

有关实际的示例结构，请参考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 等强大工具成为可能的开源生态系统。

结论#

感谢你对为 Ultralytics 开源 YOLO 项目做出贡献感兴趣。你的参与对于塑造我们软件的未来以及构建充满活力的创新和协作社区至关重要。无论你是在增强代码、报告错误还是建议新功能，你的贡献都是非常宝贵的。

我们很高兴看到你的想法变为现实，并感谢你致力于推动目标检测技术的发展。让我们一起在这个激动人心的开源旅程中不断成长与创新。

常见问题解答#

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

为 Ultralytics YOLO 开源仓库做出贡献可以改善软件，使其对整个社区而言更加稳健且功能丰富。贡献可以包括代码增强、错误修复、文档改进和新功能实现。此外，贡献还能让你与该领域的其他优秀开发者和专家进行协作，从而提升你自身的技能和声誉。有关如何开始的详细信息，请参阅通过拉取请求进行贡献部分。

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

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

I have read the CLA Document and I sign the CLA

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

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

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

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

在你的拉取请求可以合并之前，它必须通过所有 GitHub Actions 持续集成 (CI) 测试。这些测试包括代码检查、单元测试和其他检查，以确保代码符合项目的质量标准。请查看 CI 输出并修复任何问题。有关 CI 流程的详细信息和故障排除提示，请参阅GitHub Actions CI 测试部分。

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

要报告错误，请在错误报告中提供清晰且简洁的最小可复现示例。这有助于开发者快速识别并修复问题。确保你的示例既精简又足以重现该问题。有关报告错误的更详细步骤，请参阅报告错误部分。

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

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

贡献者

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

创建于 2023年11月12日更新于 3周前