跳转至内容

为 Ultralytics 开源项目做贡献

欢迎！我们很高兴您正在考虑为我们的 Ultralytics 开源 项目做出贡献。您的参与不仅有助于提高我们存储库的质量，而且还有益于整个计算机视觉社区。本指南提供了明确的指南和最佳实践，以帮助您入门。

Ultralytics 开源贡献者



观看： 如何贡献 Ultralytics 仓库 | Ultralytics 模型、数据集和文档 🚀

🤝 行为准则

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

🚀 通过 Pull Requests 贡献

我们非常感谢以 pull requests (PRs) 的形式提供的贡献。为了使审查过程尽可能顺利，请按照以下步骤操作：

  1. Fork 代码仓库: 首先，fork 相关的 Ultralytics 代码仓库（例如 ultralytics/ultralytics）到您的 GitHub 账户。
  2. 创建一个分支： 在您 Fork 的存储库中创建一个新分支，使用清晰、描述性的名称来反映您的更改（例如， fix-issue-123, add-feature-xyz）。
  3. 进行更改： 实施您的改进或修复。确保您的代码遵守项目的样式指南，并且不会引入新的错误或警告。
  4. 测试您的更改： 提交之前，请在本地测试您的更改，以确认它们按预期工作，并且不会导致回归。如果您要引入新功能，请添加测试。
  5. 提交您的更改： 使用简洁且描述性的提交消息来提交您的更改。如果您的更改解决了特定问题，请包括问题编号（例如， Fix #123: Corrected calculation error.）。
  6. 创建一个拉取请求： 从您的分支提交拉取请求到 main 原始 Ultralytics 仓库的分支。提供清晰的标题和详细的描述，解释您的更改的目的和范围。

📝 CLA 签署

在我们可以合并您的 pull request 之前，您必须签署我们的 贡献者许可协议 (CLA)。这项法律协议确保您的贡献得到适当的许可，从而允许该项目继续在 AGPL-3.0 许可下分发。

提交 pull request 后，CLA 机器人将指导您完成签名过程。要签署 CLA，只需在您的 PR 中添加一条评论，说明：

I have read the CLA Document and I sign the CLA

✍️ Google 风格 Docstrings

添加新函数或类时，请包含 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

此示例演示了如何记录命名返回值变量。使用命名返回值可以使您的代码更具自文档性且更易于理解，尤其是在处理复杂函数时。

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    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 demonstrating Google-style docstrings.

    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

注意：即使 python 将多个值作为元组返回（例如， return masks, scores），为了清晰起见和更好的工具集成，请务必单独记录每个值。当记录返回多个值的函数时：

✅ 良好 - 分别记录每个返回值： 

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.

此示例将 Google 风格的文档字符串与 Python 类型提示相结合。使用类型提示时，您可以省略文档字符串参数部分中的类型信息，因为它已在函数签名中指定。

def example_function(arg1: int, arg2: int = 4) -> bool:
    """
    Example function demonstrating Google-style docstrings.

    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

✅ GitHub Actions CI 测试

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

✨ 代码贡献的最佳实践

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

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

👀 审查 Pull Requests

审查拉取请求是另一种有价值的贡献方式。审查 PR 时：

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

🐞 报告 Bug

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

  • 检查现有问题： 首先搜索一下，看看是否已经有人报告过该错误。
  • 提供最小可复现示例： 创建一个小的、独立的、能够稳定重现问题的代码片段。 这对于高效调试至关重要。
  • 描述环境： 指定您的操作系统、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. 为你的项目授权:

    • 添加一个 LICENSE 包含完整文本的 AGPL-3.0 许可.
    • 在每个源文件顶部添加一个声明许可的声明。

  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 项目的兴趣。您的参与对于塑造我们软件的未来以及建立一个充满活力的创新和协作社区至关重要。无论您是改进代码、报告错误还是建议新功能，您的贡献都非常宝贵。

我们很高兴看到您的想法变为现实，并感谢您致力于推进目标检测技术。让我们一起在这个激动人心的开源之旅中不断成长和创新。祝您编码愉快！🚀🌟

常见问题

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

为 Ultralytics YOLO 开源存储库做贡献可以改进软件，使其对整个社区来说更加强大和功能丰富。贡献可以包括代码增强、错误修复、文档改进和新功能实现。此外，贡献使您能够与该领域的其他熟练开发人员和专家合作，从而提高您自己的技能和声誉。有关如何开始的详细信息，请参阅通过 Pull Requests 贡献部分。

如何签署 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 持续集成 (CI) 测试。这些测试包括代码检查、单元测试和其他检查，以确保代码符合项目的质量标准。请查看 CI 输出并修复任何问题。有关 CI 过程和故障排除技巧的详细信息，请参阅 GitHub Actions CI Tests 部分。

如何在 Ultralytics YOLO 仓库中报告错误？

要报告错误，请提供清晰简洁的 最小可复现示例 以及您的错误报告。这有助于开发人员快速识别和修复问题。确保您的示例足够小，但足以重现问题。有关报告错误的更多详细步骤，请参阅 报告错误 部分。

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

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



📅 创建于 1 年前 ✏️ 更新于 2 个月前
glenn-jocher RizwanMunawar UltralyticsAssistant Y-T-G willie.maddox@gmail.com leonnil MatthewNoyce Burhan-Q

评论