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

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

如果你很想参与贡献（无论是撰写文档、审查代码还是处理 issues），但又不知道从哪里开始或遇到了一些问题，我们随时准备为你提供帮助。在本文中，我们将带你了解一些开始为 Ultralytics 开源项目做出贡献的技巧。让我们直接开始吧！

Ultralytics 社区贡献的重要性#

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

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

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

如何开始 Ultralytics 开源贡献#

一个很好的起点是查看官方 Ultralytics 贡献指南。其中包含丰富的最佳实践和技巧，可帮助你充分发挥贡献的作用。第一步是通过了解贡献准则并深入了解代码，来熟悉项目现有的内容。

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

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

不同的贡献领域#

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

以下是一些选项：

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

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

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

为 Ultralytics 开源文档做出贡献#

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

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

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

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

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

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

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

你可以通过在网络浏览器中导航到 http://127.0.0.1:8000/ 来查看本地构建的文档。

在检查了清晰度、准确性和一致性后，你可以提交一个 pull request，其中包含你创建的文档的清晰描述。请务必根据文档所属和最契合的位置将其放在相应的章节中（guides、solutions、integrations 等）。请同时查看相关部分的 index.md 文件和整体的 mkdocs.yml 文件，并根据需要进行任何更新。对细节的关注将有助于审查流程顺利进行，并确保你的贡献完美融入项目中。

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

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

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

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

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

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

审查 Pull request#

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

图 5. 什么是 pull request？

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

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

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

贡献的核心在于社区#

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

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