开始使用

为 Ultralytics 开源项目做贡献

感谢你考虑为我们的 Ultralytics 开源项目做出贡献。你的参与不仅有助于提升我们仓库的质量,也能让整个计算机视觉社区受益。本指南提供了明确的规范和最佳实践,帮助你开始参与。

Ultralytics 开源贡献者



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

行为准则#

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

通过拉取请求做贡献#

我们非常感谢你通过拉取请求 (PRs)贡献代码。为使审查流程尽可能顺利,请遵循以下步骤:

  1. 复刻仓库:首先,将相关的 Ultralytics 仓库(例如 ultralytics/ultralytics)复刻到你的 GitHub 账户。
  2. 创建分支:在复刻的仓库中创建一个名称清晰、能体现修改内容的新分支(例如 fix-issue-123、add-feature-xyz)。
  3. 进行修改:实现你的改进或修复。确保代码符合项目的风格指南,且不会引入新的错误或警告。
  4. 测试你的更改:提交之前,请在本地测试更改,确认其按预期运行且不会导致回归问题。现有测试已覆盖大多数更改,因此通常不需要新增测试;如果新增测试有帮助,优先在现有测试文件中添加几行,而不是编写模拟测试。
  5. 提交修改:使用简洁且能准确描述内容的提交消息提交修改。如果修改针对某个特定问题,请注明问题编号(例如 Fix #123: Corrected calculation error.)。
  6. 创建拉取请求:将你的分支中的修改提交为拉取请求,目标分支为原始 Ultralytics 仓库的 main 分支。请提供清晰的标题和详细说明,解释修改的目的和范围。

开发环境安装#

克隆你的复刻仓库(或主仓库),并以可编辑模式(-e)安装,这样 Python 就会运行本地文件并加载每次修改,无需重新安装:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

如果要让另一个项目依赖复刻仓库而不是 PyPI 包,请将 pip 或 requirements.txt 指向复刻仓库的分支:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

文档修改#

文档源文件位于 docs/en/ 下。从仓库根目录安装开发依赖,并在创建 PR 前运行完整的严格验证:

uv pip install -e ".[dev]"
python docs/build_docs.py

验证过程会先准备生成的参考文档、宏和比较页面,然后运行 zensical build --strict。如需更快地实时预览不使用宏的页面,请运行 zensical serve。

签署 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

GitHub Actions CI 测试#

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

代码贡献最佳实践#

为 Ultralytics 项目贡献代码时,请牢记以下最佳实践:

  • 避免代码重复:尽可能复用现有代码,尽量减少不必要的参数。
  • 让修改更小、更聚焦:专注于有针对性的修改,而不是大规模改动。
  • 尽可能简化:寻找简化代码或删除不必要部分的机会。
  • 考虑兼容性:进行修改前,考虑这些修改是否可能破坏使用 Ultralytics 的现有代码。
  • 保持格式一致:Ruff Formatter 等工具有助于保持风格一致。

审查拉取请求#

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

  • 审查文档更新:确保文档已更新,以反映相关修改。
  • 评估性能影响:考虑修改可能对性能造成的影响。
  • 验证 CI 测试:确认所有持续集成测试均已通过。
  • 提供建设性反馈: 针对任何问题或疑虑,给出具体、清晰的反馈。
  • 认可付出的努力: 肯定作者的工作,营造积极协作的氛围。

报告 Bug#

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

  • 检查现有问题: 先搜索,确认该 Bug 是否已有人报告。
  • 提供最小可复现示例: 创建一段小巧、独立的代码片段,确保能够稳定复现问题。这对高效调试至关重要。
  • 描述环境: 请注明你的操作系统、Python 版本、相关库的版本(例如 torch、ultralytics)以及硬件(CPU/GPU)。
  • 说明预期行为与实际行为: 清楚说明你预期发生什么,以及实际发生了什么。请附上任何错误消息或回溯信息。

许可证#

Ultralytics 的仓库采用 GNU Affero 通用公共许可证 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 项目做出贡献。无论是改进代码、报告 bug,还是提出新功能建议,你的参与都有助于塑造我们的软件和社区。

感谢你致力于推动目标检测技术的发展,期待你的贡献。

常见问题#

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

  • 要签署贡献者许可协议(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 风格的文档字符串规范,可以确保新增内容文档齐全、易于理解。示例和指南请参阅 Google 风格的文档字符串部分。

  • 合并 Pull Request 前,必须通过所有 GitHub Actions 持续集成(CI)测试。这些测试包括代码检查、单元测试和其他检查,以确保代码符合项目的质量标准。请检查 CI 输出并修复任何问题。有关 CI 流程和故障排除技巧的详细信息,请参阅 GitHub Actions CI 测试部分。

  • 报告 Bug 时,请提供清晰、简洁的最小可复现示例。这有助于开发者快速定位并修复问题。请确保示例尽可能精简,同时足以复现问题。有关报告 Bug 的详细步骤,请参阅报告 Bug部分。

  • 如果你在项目中使用 Ultralytics YOLO 代码或模型(采用 AGPL-3.0 许可),AGPL-3.0 许可证要求你的整个项目(即衍生作品)也必须采用 AGPL-3.0 许可,并公开其完整源代码。这样可以确保软件的开源性质在其所有衍生作品中得到保留。如果你无法满足这些要求,就需要获取企业许可证。详情请参阅开源你的项目部分。

评论7

提出问题、分享结果,或帮助其他人。

  1. Mehrab-ShahbaziGitHub

    Hi I will be happy if yolo add a feature that use slding window object detection. i want to add it and pull request it. is it usefull feature? will you accebt it?(if the tests passes).

    1. Mehrab-ShahbaziGitHub

      by sliding window, i mean crop big images ti smaller tiles and at the end merge all results as one output.( it is usefull for big images as you know)

    2. Glenn JocherUltralytics

      @Mehrab-Shahbazi thank you for your interest in contributing! Sliding window object detection for large images can indeed be useful. If implemented efficiently and the tests pass, we welcome your pull request for review. Please ensure the feature aligns with the repository's design principles. For guidance, refer to our contributing guide.

  2. esssyjrGitHub

    Good evening all. I am trying to make a contribution for the dataset. I have forked and created a new branch but I could not see the folder specified for dataset. Should I just submit the .zip file to the root together with the read me, and send a pull request? Also, in my Github desktop I am unable to see Jupyter notebook as a code editor, but I manage to open the ultralytics cloned file in jupyter notebook, and uploaded the dataset. is that a good practice? Sorry for silly questions, I am new to open source contibution.

    1. Glenn JocherUltralytics

      @esssyjr thank you for your interest in contributing! For dataset contributions, please follow the Ultralytics Contribution Guide and submit your dataset in a directory with a clear structure, including train/ and val/ folders as applicable. Place the README in the same directory. Regarding Jupyter Notebook, it's fine to use it for preparing your dataset, but ensure your final submission is in the proper format per the guidelines. If you have more questions, feel free to ask on GitHub.

    2. esssyjrGitHub

      Thanks for the reply, I have successfully uploaded the zip and readme file in the a folder in root of the Ultralytics repository. I requested a pull request in which it pass all the test but merge have been blocked, waiting for a approve review. Thank YOU