开始为 Ultralytics 开源项目做贡献的建议

开源软件的基础是协作、学习和分享。开源项目是人们齐心协力、打造超越个人能力之作的绝佳方式。在 Ultralytics，我们十分重视开源原则，并始终鼓励你为我们的开源项目做贡献。

如果你热衷于贡献，无论是编写文档、审查代码还是处理问题，但不确定从哪里开始或遇到了一些困难，我们都愿意帮助你入门。本文将介绍一些技巧，帮助你开始为 Ultralytics 开源项目做贡献。

Ultralytics 社区贡献的重要性#

在了解如何贡献之前，我们先来回答为什么贡献如此重要。我们坚信 Ultralytics 社区的贡献至关重要。参与我们的开源项目，不只是帮助我们构建更好的软件。贡献者在确保我们的技术保持开放、协作和持续演进方面发挥着关键作用。你的贡献让我们的项目持续发展、易于使用，并惠及世界各地的用户和开发者！

除了构建软件，为 Ultralytics 项目做贡献也是你提升自我的绝佳机会。你可以在与经验丰富的开发者合作的过程中，提升编程、解决问题和团队协作能力，他们还能为你提供指导并分享最佳实践。你的努力可以切实影响全球数千人使用的工具。参与我们的社区也能帮助你拓展职业人脉、获得新的机会，并丰富个人作品集，让你在求职时脱颖而出。

图 1. 参与贡献的理由。图片由作者提供。

如何开始为 Ultralytics 开源项目做贡献#

一个很好的起点是查看 Ultralytics 官方贡献指南。指南中包含大量最佳实践和技巧，能帮助你充分发挥贡献的价值。首先，你需要了解项目中已有的内容，熟悉贡献指南，签署贡献者许可协议（CLA），并深入了解代码。

无论你是想参与开发，还是只想了解最新代码，下一步都是克隆 Ultralytics 代码库。完成后，你可以进入项目目录，并按下面的代码片段所示，以可编辑模式安装软件包。

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

如果你需要帮助，我们的快速入门指南提供了顺利入门所需的一切。

可以参与贡献的不同领域#

设置好环境并熟悉项目后，你可以探索不同的领域，寻找能够发挥实际影响的切入点。Ultralytics 提供了多种参与方式，你可以根据自己的技能和兴趣选择如何贡献。

以下是一些可选方式：

• 文档：参与文档编写是深入了解项目、磨练写作能力的好方法。你可以改进现有文档、补充遗漏的细节，或编写新指南，让其他人更容易参与贡献。
• 修复 Bug：如果你有一些编程经验，可以考虑修复 Bug。问题可能小到细微调整，也可能复杂得多，让你有机会为项目带来切实影响。
• 功能增强：对于准备深入参与的人来说，开发功能增强既有挑战，也能带来成就感。这可能包括添加新功能、改进现有功能，或参与制定项目路线图。
• 审查拉取请求：审查拉取请求是另一种很有价值的贡献方式，尤其是当你熟悉项目规范和最佳实践时。通过提供反馈并提出改进建议，你可以帮助维护代码库的质量和完整性。
• 参与社区讨论：如果你喜欢协作和分享想法，参与社区讨论是很好的贡献方式。你可以参与正在进行的讨论、提出新想法，或分享见解和解决方案来帮助他人。

这些领域各有独特的贡献方式，你可以选择最符合自己优势和兴趣的方向。请记住，无论贡献多么微小，每一份贡献都在帮助 Ultralytics 成长和发展中发挥着重要作用。

图 2. 在不断壮大的社区中，每一份贡献都弥足珍贵。图片来源：Envato Elements。

为 Ultralytics 开源文档做贡献#

为 Ultralytics 文档做贡献时，请务必先查看现有文档，并留意指出需要改进之处的问题或讨论。这样有助于确保你的贡献聚焦于最需要改进的地方。

撰写或编辑文档时，请记住遵循项目指南对于保持一致性至关重要。下面是一些格式方面的建议：

• 请始终使用 Markdown 格式。
• 每份文档都应以清晰的简介开篇，并使用简洁易懂的语言。
• 列表请使用项目符号，链接文字请具有描述性，图片大小请控制在 1 MB 以下，以便页面快速加载。
• 如果你对格式有疑问，可以查看以往文档的格式，轻松核对自己的排版。

图 3. Markdown 格式示例（左）和最终呈现的文档（右）。图片由作者提供。

完成草稿后，务必在本地构建文档并预览。这样你可以在提交前发现问题。首先，克隆代码库并进入项目目录：

git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

接下来，安装所需的依赖项：

pip install -e ".[dev]"

最后，构建文档并在本地运行，以检查你的更改：

python docs/build_docs.py
python -m http.server --directory site

在浏览器中访问 http://127.0.0.1:8000/，即可查看本地构建的文档。

检查文档是否清晰、准确且一致后，你可以提交拉取请求，并清楚说明所创建文档的内容。请根据文档的归属和最合适的位置，将其放入相应部分（例如指南、解决方案、集成等）。此外，请查看 index.md 文件中相关的章节，以及整体的 mkdocs.yml 文件，并按需更新。注重细节有助于顺利完成审核，并确保你的贡献与项目良好集成。

为开源代码做贡献时需要注意的事项#

为 Ultralytics 项目贡献代码时，遵循有助于确保代码整洁、易于维护并方便集成的最佳实践非常重要。以下是一些需要牢记的要点：

• 避免代码重复：尽可能复用现有代码，并尽量减少不必要的参数。
• 进行小而集中的更改：与其进行大规模修改，不如专注于小范围、有针对性的更改。
• 简化或删除代码：寻找简化代码或删除不必要部分的机会。
• 编写有效的 文档字符串：清楚说明代码的作用，并链接到相关资源。
• 避免不必要的依赖项：只有在绝对必要时才添加依赖项。

图 4. 源代码文档编写最佳实践。

考虑代码库的长期可维护性也至关重要。在进行任何更改之前，先问问自己：这些修改是否可能破坏他人使用 Ultralytics 编写的现有代码？如果会，请考虑如何解决这个问题，并确保更改尽可能兼容。

完成待贡献的代码后，你需要对其进行测试。你可以使用 pytest 等框架，在提交前测试更改。保持代码格式一致也是贡献中非常重要的一环。Ruff 等工具可以帮助你维持风格一致，并发现代码中常见的错误或不一致之处。

审查拉取请求#

审查拉取请求（PR）是很好的贡献方式！当有人请求将其更改合并到主项目中时，就会发起 PR。这有助于 Ultralytics 项目顺利运行。审查 PR 时，请确保你理解这些更改的原因。作者应清楚说明更新的目的和好处，并在 PR 中提供充分测试的证据。

图 5. 什么是拉取请求？

下面来看看几个需要重点关注的要点。

• 检查单元测试：检查 PR 是否包含针对新功能或更改的测试，以确认代码能按预期运行且不会引入问题。
• 审查文档更新：确认文档已更新，以反映更改或新功能，包括示例、API 参考和其他相关细节。
• 评估对性能的影响：考虑这些更改会如何影响性能。如有需要，可要求提供性能基准测试或进行额外测试。
• 验证 CI 测试：确保所有持续集成（CI）测试均已通过，包括代码格式检查和单元测试结果检查。
• 协作修复问题：如果测试失败，请与作者合作解决问题，然后再批准 PR。

作为审查者，请确保反馈具体明确，清楚指出任何问题或顾虑。提出改进建议，并通过提问帮助作者思考潜在问题。鼓励作者遵循编码、测试和文档编写方面的最佳实践，也不妨为作者推荐有帮助的资源。最后但同样重要的是，始终认可作者为 PR 付出的努力。积极的反馈有助于开源社区保持友好、协作的氛围。

贡献的核心是社区#

为 Ultralytics 这样的开源项目做贡献，能让你感受到社区的鼓舞。无论是编写代码、审查 PR、更新文档还是参与讨论，每一份努力都能推动项目成长和演进。你可以在 GitHub、Discord、Reddit或其他论坛上回答问题或参与交流，这些都是做贡献并与他人建立联系的有效方式。请记住，无论贡献多么微小，都会产生重要影响，并帮助营造协作互助的环境，让每个参与者都受益！

在 Ultralytics，我们热衷于推动开源社区创新。访问我们的 GitHub 代码库，了解最新进展。加入充满活力的社区，看看我们如何在农业和制造业等行业发挥影响力。