在 GitHub 上编辑页面 (EN)

为 Ultralytics 开源项目做出贡献

欢迎！我们非常高兴你能考虑为我们的 Ultralytics 开源项目做出贡献。你的参与不仅有助于提升我们存储库的质量，还能惠及整个计算机视觉社区。本指南提供了明确的规范和最佳实践，帮助你快速上手。

Ultralytics 开源贡献者



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

🤝 行为准则

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

🚀 通过 Pull Request 进行贡献

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

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

📝 CLA 签署

在我们合并你的 Pull Request 之前，你必须签署我们的贡献者许可协议 (CLA)。这份法律协议确保了你的贡献得到适当许可，使项目能够继续根据 AGPL-3.0 许可证进行分发。

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

I have read the CLA Document and I sign the CLA

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

✅ GitHub Actions CI 测试

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

✨ 代码贡献最佳实践

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

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

👀 审查 Pull Request

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

  • 检查单元测试： 验证 PR 是否包含针对新功能或更改的测试。
  • 审查文档更新： 确保文档已更新以反映更改。
  • 评估性能影响： 考虑更改可能如何影响性能。
  • 验证 CI 测试： 确认所有持续集成测试均已通过。
  • 提供建设性反馈： 提供关于任何问题或顾虑的明确、具体的反馈。
  • 认可付出： 认可作者的工作，以维持积极的协作氛围。

🐞 报告 Bug

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

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

📜 许可证

Ultralytics 的存储库使用 GNU Affero General Public License 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 许可证下公开提供。

  1. 选择你的起点：

  2. 为你的项目授权：

    • Add a LICENSE file containing the full text of the AGPL-3.0 license.
    • 在每个源文件的顶部添加版权说明，指明该许可证。

  3. 发布你的源代码：

    • 确保你整个项目的源代码均可公开访问（例如在 GitHub 上）。这包括：
      • 包含 YOLO 模型或代码的完整大型应用程序或系统。
      • 对原始 Ultralytics YOLO 代码所做的任何修改。
      • 用于训练、验证和推理的脚本。
      • 如果经过修改或微调，请提供模型权重。
      • 配置文件和环境设置（requirements.txt, Dockerfiles）。
      • 如果属于Web 应用程序的一部分，则需包含后端和前端代码。
      • 你修改过的任何第三方库。
      • 如果运行/重新训练需要且可重新分发，请提供训练数据。

  4. 清晰记录：

    • 更新你的 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 项目做出贡献感兴趣。你的参与对于塑造我们软件的未来以及构建一个充满创新与协作的活力社区至关重要。无论你是完善代码、报告 Bug 还是建议新功能，你的贡献都弥足珍贵。

我们很高兴看到你的想法付诸实践，并感谢你致力于推动目标检测技术的发展。让我们携手在这激动人心的开源旅程中继续成长与创新。

常见问题 (FAQ)

为什么要为 Ultralytics YOLO 开源存储库做出贡献？

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

如何签署 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 贡献时强制要求使用它们？

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

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

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

我该如何报告 Ultralytics YOLO 仓库中的错误？

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

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

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

Contributors
在 GitHub 上编辑页面 (EN)
GLglenn-jocher22RIRizwanMunawar3PDpderrenger1Y-Y-T-G1WIWillie Maddox1LEleonnil1MAMatthewNoyce1BUBurhan-Q1

评论