跳至内容

为Ultralytics 开放源码项目做贡献

欢迎您我们很高兴您考虑为我们的 Ultralytics开源项目。您的参与不仅有助于提高我们资源库的质量，还能造福整个计算机视觉社区。本指南提供了明确的指导原则和最佳实践，帮助您开始工作。

Ultralytics 开源贡献者



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

行为守则

为了确保为每个人提供一个温馨、包容的环境，所有投稿人都必须遵守我们的《行为准则》。尊重、友善和专业精神是我们社区的核心。

🚀通过拉取请求做出贡献

我们非常感谢您以拉动请求（PR）的形式为我们做出贡献。为使审核过程尽可能顺利，请遵循以下步骤：

  1. 分叉仓库：首先将相关的Ultralytics 软件仓库（如ultralyticsultralyticsultralytics）分叉到你的 GitHub 账户。
  2. 创建分支： 在你的分叉版本库中创建一个新分支，用一个清晰的、描述性的名称来反映你所做的改动（例如、 fix-issue-123, add-feature-xyz).
  3. 进行修改：实施您的改进或修正。确保您的代码符合项目的风格指南，并且不会引入新的错误或警告。
  4. 测试更改：在提交之前，请在本地测试您的更改，以确认它们能按预期运行，并且不会导致回归。如果要引入新功能，请添加测试。
  5. 提交更改： 用简明扼要的提交信息提交更改。如果您的更改针对的是特定问题，请包含问题编号（例如 Fix #123: Corrected calculation error.).
  6. 创建拉取请求 从你的分支向 main 分支。提供明确的标题和详细描述，说明更改的目的和范围。

📝 CLA 签名

在我们合并您的拉取请求之前，您必须签署我们的《贡献者许可协议》（CLA）。该法律协议可确保您的贡献获得正确的许可，从而使项目能继续在AGPL-3.0 许可下发布。

提交拉取请求后，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

本例演示了如何记录命名的返回变量。使用命名的返回值可以使代码更加自文档化，也更容易理解，尤其是对于复杂的函数。

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 docstrings 和Python 类型提示。使用类型提示时，可以省略 docstring 参数部分的类型信息，因为函数签名中已经指定了这些信息。

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

对于较小或较简单的功能，单行 docstring 可能就足够了。这些文档应该是简洁而完整的句子，以大写字母开头，句号结尾。

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

✅ GitHub 操作 CI 测试

所有拉取请求必须通过GitHub Actions Continuous Integration(CI) 测试才能合并。这些测试包括内衬、单元测试和其他检查，以确保您的更改符合项目的质量标准。查看 CI 输出并解决出现的任何问题。

✨ 代码贡献的最佳做法

在为Ultralytics 项目贡献代码时，请牢记这些最佳实践：

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

👀 审查拉取请求

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

  • 检查单元测试：验证 PR 是否包含新功能或更改的测试。
  • 审查文件更新：确保更新文件以反映变化。
  • 评估性能影响：考虑更改会如何影响性能。
  • 验证 CI 测试：确认所有持续集成测试通过。
  • 提供建设性反馈：就任何问题或疑虑提供具体、明确的反馈。
  • 认可努力：肯定作者的工作，保持积极的合作氛围。

🐞 报告错误

我们高度重视错误报告，因为它们有助于我们提高项目的质量和可靠性。通过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 许可意味着在AGPL-3.0 许可下公开项目的全部相应源代码。

  1. 选择起点

  2. 为您的项目颁发许可证：

    • 添加一个 LICENSE 文件，其中载有 AGPL-3.0 许可.
    • 在每个源文件的顶部添加一个通知，说明许可证。

  3. 发布源代码

    • 让您的 整个项目的源代码 可公开访问（如在 GitHub 上）。这包括
      • 包含YOLO 模型或代码的完整的大型应用程序或系统。
      • 对最初的Ultralytics YOLO 代码所做的任何修改。
      • 用于训练、验证和推理的脚本。
      • 修改或微调模型权重。
      • 配置文件环境设置 (requirements.txt, Dockerfiles).
      • 后端和前端代码（如果是网络应用程序的一部分）。
      • 您修改过的任何第三方库。
      • 如果需要运行/重新训练，可提供训练数据。

  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），请在提交拉取请求后按照 CLA 机器人提供的说明进行操作。此过程可确保您的贡献在AGPL-3.0 许可下得到正确授权，从而维护开源项目的法律完整性。在您的拉取请求中添加注释，说明

I have read the CLA Document and I sign the CLA

更多信息，请参阅CLA 签名部分。

什么是Google-style docstrings，为什么Ultralytics YOLO 投稿时需要使用它们？

Google-样式的文档说明为函数和类提供了简洁明了的文档，提高了代码的可读性和可维护性。这些文档以特定的格式规则概述了函数的目的、参数和返回值。在向Ultralytics YOLO 投稿时，遵循Google 样式的 docstrings 可确保您添加的内容文档齐全且易于理解。有关示例和指南，请访问Google-style docstrings部分。

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

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

如何报告Ultralytics YOLO 版本库中的错误？

要报告错误，请在报告错误的同时提供一个简洁明了的 "最小可重现示例"。这有助于开发人员快速识别并修复问题。确保您的示例是最小的，但足以复制问题。有关报告错误的更多详细步骤，请参阅报告错误部分。

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

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



📅创建于 1 年前 ✏️已更新 25 天前
翔宇 鸽子 里兹万-穆纳瓦 马修-诺伊斯 超解助手 布尔汗-Q

评论