开始为 Ultralytics 开源项目做贡献的技巧

开源软件的基础是协作、学习和共享。开源项目是人们聚在一起构建超越自身成就的伟大方式。在 Ultralytics，我们将开源原则铭记于心，并始终鼓励你为我们的开源项目做出贡献。

如果你热衷于做出贡献，无论是编写文档、审查代码还是解决问题，但不确定从何处开始或正面临一些 issues，我们随时为你提供帮助。在本文中，我们将为你提供一些开始为 Ultralytics 开源项目做出贡献的建议。让我们开始吧！

Link to this sectionUltralytics 社区贡献的重要性#

在了解如何贡献之前，让我们先回答为什么贡献如此关键这个问题。我们坚信 Ultralytics 社区贡献的重要性。通过参与我们的开源项目，你不仅仅是在帮助我们构建更好的软件。贡献者在确保我们的技术保持开放、协作和不断发展方面发挥着关键作用。你的贡献使我们的项目能够蓬勃发展、保持 accessible，并造福全球的用户和开发者！

除了创造尖端的软件外，为 Ultralytics 项目做出贡献对你个人成长来说也是一个绝佳的机会。你可以在与经验丰富的开发者并肩工作时提高自己的编码、解决问题和团队协作能力，他们可以提供指导并分享最佳实践。你的努力可以对全球成千上万的人使用的工具产生实际影响。与我们的社区互动还可以帮助你扩展职业人脉、开启新的机会，并提升你的个人作品集，从而在雇主面前脱颖而出。

图 1. 做出贡献的原因。图片由作者提供。

Link to this section如何开始 Ultralytics 开源贡献#

一个很好的起点是查看 官方 Ultralytics 贡献指南。其中汇集了最佳实践和建议，可帮助你充分利用自己的贡献。第一步是通过了解 贡献准则 并深入研究代码，来熟悉项目中已有的内容。

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

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

Link to this section不同的贡献领域#

一旦你配置好环境并熟悉了项目，就可以探索能够产生重大影响的不同领域。Ultralytics 提供了多种参与方式，你可以根据自己的技能和兴趣选择贡献方式。

以下是一些选项：

• 文档: 为文档做出贡献是深入了解项目同时磨练写作技巧的绝佳方式。你可以通过改进现有文档、添加缺失的详细信息或创建新的指南来提供帮助，从而使其他人更容易做出贡献。
• Bug 修复: 如果你有一定的编码经验，可以考虑修复 Bug。这些工作范围广泛，从小调整到复杂的问题都有，让你有机会为项目产生切实的影响。
• 功能增强: 对于准备深入研究的人来说，进行功能增强既具有挑战性又有回报。这可能涉及添加新功能、改进现有功能或致力于项目路线图。
• Pull request 审查: 审查 Pull request 是另一种有价值的贡献方式，特别是如果你熟悉项目的标准和最佳实践的话。通过提供反馈和建议改进，你可以帮助维护代码库的质量和完整性。
• 社区讨论: 如果你喜欢协作和分享想法，参与社区讨论是贡献的绝佳方式。参与正在进行的对话、提出新点子，或通过提供你的见解和解决方案来帮助他人。

以上每个领域都提供了一种独特的贡献方式，你可以选择最符合你优势和兴趣的领域。请记住，每一份贡献，无论大小，都在帮助 Ultralytics 成长和发展中发挥着关键作用。

图 2. 每一次贡献在我们不断成长的社区中都受到重视。图片来源：Envato Elements。

Link to this section为 Ultralytics 开源文档做出贡献#

为 Ultralytics 文档做出贡献时，请务必审查现有文档，并检查是否有任何需要改进的问题或讨论。这样做有助于确保你的贡献集中在最需要的地方。

在编写或编辑时，请记住遵循项目准则以保持一致性至关重要。以下是一些格式建议：

• 始终使用 Markdown 格式。
• 每份文档都以清晰的介绍开始，并保持语言简洁易懂。
• 列表使用项目符号，链接使用描述性文本，图像大小应小于 1 MB，以便页面快速加载。
• 如果你对格式有疑问，检查以前文档的格式是一个轻松校对格式的方法。

图 3. Markdown 格式示例（左侧）和最终可视化文档（右侧）。图片由作者提供。

草稿完成后，通过在本地构建文档来预览它非常重要。你可以在提交前捕获任何问题。为此，先克隆仓库并导航到项目目录：

接下来，你可以安装必要的依赖项：

最后，在本地提供文档服务以审查你的更改：

你可以通过在 Web 浏览器中访问 http://127.0.0.1:8000/ 来查看本地构建的文档。

在检查清晰度、准确性和一致性后，你可以提交一个 Pull request，并对所创建的文档进行清晰的描述。请确保根据文档所属和最适合的位置将其放置在适当的章节中（guides, solutions, integrations 等）。请同时查看相关章节的 index.md 文件以及整体的 mkdocs.yml 文件，并根据需要进行任何更新。关注细节将有助于审查过程顺利进行，并确保你的贡献能够很好地集成到项目中。

Link to this section为开源代码做出贡献时需要牢记的事项#

在为 Ultralytics 项目做出代码贡献时，遵循最佳实践以帮助确保代码整洁、可维护且易于集成非常重要。以下是一些需要牢记的关键点：

• 避免代码重复：尽可能重用现有代码并最大限度地减少不必要的参数。
• 进行更小、更专注的更改：专注于更小、有针对性的更改，而不是大规模的修改。
• 简化或删除代码：寻找简化代码或删除不必要部分的机会。
• 编写有效的 docstrings：清晰地解释你的代码功能并链接到相关资源。
• 避免不必要的依赖项：仅在绝对必要时才添加依赖项。

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

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

开发出贡献代码后，你需要对其进行测试。你可以在提交之前使用像 pytest 这样的框架来测试你的更改。一致的代码格式也是你贡献中非常重要的一方面。像 Ruff Formatter 这样的工具可以帮助你保持风格一致性，并检测代码中的任何逻辑 Bug 或不一致之处。

Link to this section审查 Pull request#

审查 Pull request (PR) 是贡献的绝佳方式！当有人请求将其更改合并到主项目中时，就会提出一个 PR。它有助于保持 Ultralytics 项目的顺利运行。当你审查 PR 时，请确保你了解为什么要进行这些更改。作者应该清楚地解释更新的目的和好处，并且你应该在他们的 PR 中看到详尽测试的证据。

图 5. 什么是 Pull request？

让我们来看看几个需要关注的关键事项。

• 检查单元测试：检查 PR 是否包含新功能或更改的测试，以确认代码按预期工作并且不会引入问题。
• 审查文档更新：验证文档是否已更新以反映更改或新功能，包括示例、API 参考和其他相关详细信息。
• 评估性能影响：考虑更改如何影响性能。如果需要，请求性能基准测试或额外测试。
• 验证 CI 测试：确保所有 持续集成 (CI) 测试通过，包括代码格式检查和单元测试结果。
• 协作修复：如果任何测试失败，请在批准 PR 之前与作者合作解决问题。

作为审查者，请务必提供具体且清晰的反馈，指出任何问题或疑虑。提供改进建议并提出问题，帮助作者思考潜在的问题。鼓励他们遵循编码、测试和文档方面的最佳实践，并且不要犹豫，向他们推荐有用的资源。最后但同样重要的一点是，始终认可作者在 PR 中所付出的努力。积极的反馈有助于在开源社区中保持友好和协作的氛围。

Link to this section贡献的核心在于社区#

为像 Ultralytics 这样的开源项目做出贡献可以带给你一种鼓舞人心的社区感。无论你是编写代码、审查 PR、更新文档还是参与讨论，每一份努力都在帮助项目成长和发展。回答问题或参与对话（无论是在 GitHub、Discord、Subreddit 还是其他论坛上）都是一种有价值的贡献方式，并能与他人建立联系。请记住，你的贡献无论多么微小，都会产生重大影响，并有助于为所有参与者营造一个协作和支持的环境！

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