为 Ultralytics 开源项目做贡献#

欢迎！我们非常高兴你考虑为我们的 Ultralytics 开源 项目做贡献。你的参与不仅有助于提升我们代码仓库的质量，也会惠及整个计算机视觉社区。本指南提供了清晰的准则和最佳实践，帮助你开始贡献。

行为准则#

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

通过拉取请求进行贡献#

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

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）。该法律协议确保你的贡献获得适当授权，使项目能够继续依据 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 持续集成测试#

所有拉取请求都必须通过 GitHub Actions 持续集成（CI）测试后才能合并。这些测试包括代码检查、单元测试和其他检查，用于确保你的更改符合项目的质量标准。请查看 CI 输出并处理出现的任何问题。

代码贡献的最佳实践#

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

• 避免代码重复： 尽可能复用现有代码，并尽量减少不必要的参数。
• 进行更小且专注的更改： 专注于针对性修改，而不是大规模更改。
• 尽可能简化： 寻找简化代码或移除不必要部分的机会。
• 考虑兼容性： 进行更改前，考虑这些更改是否可能破坏使用 Ultralytics 的现有代码。
• 使用一致的格式： Ruff Formatter 等工具有助于保持风格一致。
• 添加适当的测试： 为新功能包含测试，确保其按预期工作。

审查拉取请求#

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

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

报告错误#

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

• 检查现有问题： 先进行搜索，确认该错误是否已经有人报告。
• 提供最小可复现示例： 创建一个小型且自包含的代码片段，以稳定地复现问题。这对于高效调试至关重要。
• 描述环境： 指定你的操作系统、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. 选择起点：

   • 复刻 Ultralytics YOLO： 如果你的项目是在其基础上紧密构建的，直接复刻 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 项目做贡献。你的参与对于塑造我们软件的未来以及建设充满活力的创新与协作社区至关重要。无论你是在改进代码、报告错误还是建议新功能，你的贡献都弥足珍贵。

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

常见问题#