为 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)）。

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 时：

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

报告 Bug#

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

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

许可证#

Ultralytics 的代码仓库采用GNU Affero 通用公共许可证第 3.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. 选择起点：

   • Fork Ultralytics YOLO： 如果你的项目是在 Ultralytics YOLO 基础上构建的，可以直接 Fork Ultralytics YOLO 代码仓库。
   • 使用 Ultralytics 模板： 从 Ultralytics 模板代码仓库开始，获得一个整洁、模块化且集成 YOLO 的项目结构。

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，还是提出新功能建议，你的贡献都弥足珍贵。

我们很期待看到你的想法变成现实，也感谢你致力于推动目标检测技术的发展。让我们携手在这段激动人心的开源旅程中不断成长、持续创新。

常见问题#