跳至内容

为Ultralytics 开放源码项目做贡献

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

Ultralytics 开源贡献者

行为准则

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

通过拉动请求做出贡献

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

  1. 分叉仓库：首先将Ultralytics YOLO 仓库分叉到你的 GitHub 账户。

  2. 创建分支：在你的分叉版本库中创建一个新分支，用一个清晰、描述性的名称来反映你的改动。

  3. 进行修改：确保您的代码符合项目的风格指南，并且不会引入任何新的错误或警告。

  4. 测试更改：在提交之前，请在本地测试您的更改，以确认它们是否按预期运行，并且不会导致任何新问题。

  5. 提交更改用简明扼要的提交信息提交更改。如果您的更改涉及特定问题，请在提交信息中注明问题编号。

  6. 创建拉取请求：从您的分叉仓库向Ultralytics YOLO 主仓库提交拉取请求。清楚详细地解释你的改动以及这些改动是如何改进项目的。

CLA 签署

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

提交拉取请求后，CLA 机器人将引导您完成签署流程。要签署 CLA，只需在您的 PR 中添加注释说明即可：

I have read the CLA Document and I sign the CLA

Google-文档字符串风格

添加新函数或类时，请包含Google 样式的 文档说明。这些文档说明提供了清晰的标准化文档，有助于其他开发人员理解和维护您的代码。

文档字符串示例

本例说明了Google 样式的 docstring。确保输入和输出 types 总是用括号括起来，例如 (bool).

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

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument, with a default value of 4.

    Returns:
        (bool): True if successful, False otherwise.

    Examples:
        >>> result = example_function(1, 2)  # returns False
    """
    if arg1 == arg2:
        return True
    return False

本示例包含Google 样式的 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, with a default value of 4.

    Returns:
        True if successful, False otherwise.

    Examples:
        >>> result = example_function(1, 2)  # returns False
    """
    if arg1 == arg2:
        return True
    return False

对于较小或较简单的函数，单行 docstring 可能就足够了。docstring 必须使用三个双引号，是一个完整的句子，以大写字母开头，以句号结尾。

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

GitHub 操作 CI 测试

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

报告错误

我们高度重视错误报告，因为它们有助于我们保持项目的质量。在报告错误时，请提供一个最小可重现示例--一个能持续重现问题的简单明了的代码示例。这样我们就能快速识别并解决问题。

许可证

Ultralytics 的软件源使用GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。该许可证提倡软件开发的开放性、透明度和协作改进。它确保所有用户都有使用、修改和共享软件的自由，从而培养了一个强大的协作和创新社区。

我们鼓励所有贡献者熟悉AGPL-3.0 许可证的条款，以便以有效和合乎道德的方式为Ultralytics 开放源码社区做出贡献。

通过YOLO 和AGPL-3.0 合规性开源您的项目

如果您计划使用YOLO 模型开发和发布自己的项目，GNU Affero 通用公共许可证 v3.0 (AGPL-3.0) 可确保所有衍生作品保持开放和可访问性。本节提供包括步骤、最佳实践和要求在内的指导，帮助您在开源项目的同时遵守AGPL-3.0 。

启动项目的选择

您可以使用其中一种方法启动您的项目：

  1. 分叉Ultralytics YOLO 资源库
    直接从https://github.com/ultralytics/ultralytics 叉叉 Ultralytics YOLO 官方软件源。

    • 如果计划直接在最新的YOLO 实现上构建，请使用此选项。
    • 根据需要修改分叉代码，同时确保符合AGPL-3.0 。

  2. 从Ultralytics 模板库开始
    使用Ultralytics 模板库，网址是https://github.com/ultralytics/template。

    • 是启动一个简洁、模块化、预配置最佳实践的项目的理想选择。
    • 该选项为集成或扩展YOLO 模型的项目提供了一个轻量级的起点。

开源所需

为遵守AGPL-3.0 ，您必须公开项目的以下组成部分：

  1. 您的整个项目源代码

    • 包括包含YOLO 模型、脚本和实用程序的大型项目的所有代码。

  2. 模型权重（如果修改）：

    • 作为开源项目的一部分，共享任何经过微调或修改的模型权重。

  3. 配置文件：

    • 提供配置文件，如 .yaml 或 .json 定义了训练设置、超参数或部署配置。

  4. 训练数据（如可再分发）：

    • 如果包含可重新发布的预处理或生成的数据，请确保将其作为资源库的一部分或明确链接。

  5. 网络应用组件：

    • 如果您的项目是网络应用程序，请包含所有后台和前台源代码，尤其是服务器端组件。

  6. 文件：

    • 包括关于如何使用、构建和扩展项目的清晰文档。

  7. 构建和部署脚本

    • 共享用于设置环境、构建应用程序和部署的脚本，例如 Dockerfiles, requirements.txt或 Makefiles.

  8. 测试框架：

    • 将单元测试和集成测试等测试用例开源，以确保可重现性和可靠性。

  9. 第三方修改：

    • 提供您修改过的任何第三方库的源代码。

项目开源步骤

  1. 选择起点

    • 分叉Ultralytics YOLO 资源库，或从Ultralytics 模板资源库开始。

  2. 设置许可证：

    • 添加一个 LICENSE 文件，其中包含AGPL-3.0 文本。

  3. 贷记上游捐款：

    • 在 README 中注明Ultralytics YOLO 。例如 
      This project builds on [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

  4. 公开你的代码

    • 将整个项目（包括上述组件）推送到 GitHub 公共仓库。

  5. 记录你的项目

    • 写清楚 README.md 并附有设置、使用和贡献说明。

  6. 启用捐款：

    • 建立问题跟踪器和贡献指南，促进合作。

通过遵循这些步骤并确保包含所有必要组件，您将遵守AGPL-3.0 并为开源社区做出有意义的贡献。让我们继续共同促进计算机视觉领域的合作与创新！🚀

资源库结构示例

以下是AGPL-3.0 项目的结构示例。详见https://github.com/ultralytics/template。

my-yolo-project/
│
├── LICENSE               # AGPL-3.0 license text
├── README.md             # Project overview and license information
├── src/                  # Source code for the project
│   ├── model.py          # YOLO-based model implementation
│   ├── utils.py          # Utility scripts
│   └── ...
├── pyproject.toml        # Python dependencies
├── tests/                # Unit and integration tests
├── .github/              # GitHub Actions for CI
│   └── workflows/
│       └── ci.yml        # Continuous integration configuration
└── docs/                 # Project documentation
    └── index.md

通过遵循本指南，您可以确保您的项目在为开源社区做出贡献的同时始终符合AGPL-3.0 的要求。您的遵守加强了协作、透明和可访问性的精神，而正是这种精神推动了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) 测试。这些测试包括inting、单元测试和其他检查，以确保代码符合

项目的质量标准。检查 CI 输出并修复任何问题。有关 CI 流程和故障排除技巧的详细信息，请参阅GitHub Actions CI Tests部分。

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

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

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

评论