Советы для начала участия в open-source проектах Ultralytics

Основа открытого программного обеспечения — это сотрудничество, обучение и обмен опытом. Open-source проекты — это отличный способ объединиться, чтобы создать что-то большее, чем мы сами. В Ultralytics мы глубоко ценим принципы открытого ПО и всегда призываем тебя вносить вклад в наши open-source проекты.

Если ты хочешь внести свой вклад — будь то написание документации, проверка кода или исправление ошибок, — но не знаешь, с чего начать, или столкнулся с какими-то проблемами, мы готовы тебе помочь. В этой статье мы расскажем о нескольких советах, которые помогут тебе начать работу с open-source проектами Ultralytics. Поехали!

Link to this sectionВажность вклада сообщества Ultralytics#

Прежде чем мы перейдем к тому, как внести свой вклад, давай ответим на вопрос, почему это так важно. Мы твердо верим в значимость вклада сообщества Ultralytics. Участвуя в наших open-source проектах, ты делаешь гораздо больше, чем просто помогаешь нам создавать лучшее ПО. Участники играют ключевую роль в том, чтобы наши технологии оставались открытыми, совместными и постоянно развивающимися. Твой вклад помогает нашим проектам процветать, оставаться доступными и приносить пользу пользователям и разработчикам по всему миру!

Помимо создания передового ПО, участие в проектах Ultralytics — это еще и отличная возможность для твоего профессионального роста. Ты можешь развивать навыки программирования, решения задач и командной работы, взаимодействуя с опытными разработчиками, которые поделятся советами и лучшими практиками. Твои усилия могут оказать реальное влияние на инструменты, которыми пользуются тысячи людей по всему миру. Взаимодействие с нашим сообществом поможет тебе расширить профессиональные связи, открыть новые возможности и дополнить свое портфолио, чтобы выделиться перед потенциальными работодателями.

Рис. 1. Причины внести вклад. Изображение автора.

Link to this sectionКак начать вносить вклад в open-source проекты Ultralytics#

Отличное место для старта — ознакомиться с официальным руководством по внесению вклада в Ultralytics. Оно наполнено лучшими практиками и советами, которые помогут тебе получить максимум от своего вклада. Первым шагом будет знакомство с тем, что уже является частью проекта: изучи руководящие принципы внесения вклада и погрузись в код.

Независимо от того, хочешь ли ты участвовать в разработке или просто изучить актуальный код, следующим шагом будет клонирование репозитория Ultralytics. Сделав это, перейди в директорию проекта и установи пакет в редактируемом режиме, как показано в фрагменте кода ниже.

Если тебе нужна помощь, в нашем руководстве по быстрому старту есть всё необходимое для легкого начала работы.

Link to this sectionРазличные области, в которые можно внести вклад#

Как только ты настроишь свое окружение и познакомишься с проектом, сможешь изучить разные области, в которых ты принесешь реальную пользу. Ultralytics предлагает несколько способов участия, и ты можешь выбрать то, что соответствует твоим навыкам и интересам.

Вот некоторые из вариантов:

• Документация: Вклад в документацию — это отличный способ погрузиться в проект, оттачивая навыки письма. Ты можешь помочь, улучшив существующую документацию, добавив недостающие детали или создав новые руководства, которые облегчат внесение вклада другим.
• Исправление ошибок: Если у тебя есть опыт в программировании, попробуй поработать над исправлением багов. Это могут быть как мелкие правки, так и более сложные задачи, что даст тебе возможность внести ощутимый вклад в проект.
• Улучшение функционала: Для тех, кто готов углубиться, работа над улучшением функций может быть одновременно сложной и полезной. Это может включать добавление новых функций, оптимизацию существующих или работу над дорожной картой проекта.
• Проверка pull request: Обзор pull request — еще один ценный способ участия, особенно если ты знаком со стандартами и лучшими практиками проекта. Предоставляя обратную связь и предлагая улучшения, ты помогаешь поддерживать качество и целостность кодовой базы.
• Обсуждения в сообществе: Участие в дискуссиях — отличный вариант для тех, кто любит сотрудничество и обмен идеями. Принимай участие в текущих беседах, предлагай идеи или помогай другим, делясь своими знаниями и решениями.

Каждая из этих областей предлагает уникальный путь, и ты можешь выбрать ту, что лучше всего соответствует твоим сильным сторонам и интересам. Помни, что каждый вклад, каким бы малым он ни был, играет ключевую роль в развитии Ultralytics.

Рис. 2. В нашем растущем сообществе ценен любой вклад. Источник изображения: Envato Elements.

Link to this sectionВклад в документацию Ultralytics с открытым исходным кодом#

При работе над документацией Ultralytics обязательно ознакомься с уже существующими материалами, а также изучи вопросы или обсуждения, где упоминаются области, требующие улучшения. Это поможет убедиться, что твой вклад направлен туда, где он действительно необходим.

При написании или редактировании помни, что главное — следовать правилам проекта для сохранения согласованности. Вот несколько советов по оформлению:

• Всегда используй Markdown-разметку.
• Начинай каждый документ с четкого введения и пиши простым, понятным языком.
• Используй маркированные списки, дескриптивный текст для ссылок и изображения размером менее 1 МБ, чтобы страницы загружались быстро.
• Если у тебя возникнут вопросы по форматированию, простой способ проверить себя — посмотреть, как оформлена уже существующая документация.

Рис. 3. Пример Markdown-разметки (слева) и итоговый визуализированный документ (справа). Изображение автора.

После создания черновика важно предварительно просмотреть его, собрав документацию локально. Так ты сможешь заметить любые ошибки перед отправкой. Для этого начни с клонирования репозитория и перехода в директорию проекта:

Затем установи необходимые зависимости:

Наконец, запусти документацию локально, чтобы просмотреть изменения:

Ты можешь увидеть локально собранную документацию, перейдя по адресу http://127.0.0.1:8000/ в браузере.

После проверки на ясность, точность и последовательность отправь pull request с четким описанием созданного документа. Обязательно помести документ в соответствующий раздел, где он будет смотреться лучше всего (guides, solutions, integrations и т. д.). Пожалуйста, ознакомься с файлом index.md для соответствующих разделов и общим файлом mkdocs.yml, внеся необходимые обновления. Внимание к деталям поможет процессу проверки пройти гладко и гарантирует, что твой вклад будет успешно интегрирован в проект.

Link to this sectionЧто стоит помнить при внесении вклада в open-source код#

При внесении правок в код проекта Ultralytics важно придерживаться лучших практик, которые гарантируют чистоту, поддержку и легкость интеграции твоего кода. Вот несколько ключевых моментов:

• Избегай дублирования кода: по возможности используй повторно существующий код и минимизируй лишние аргументы.
• Делай небольшие, сфокусированные правки: фокусируйся на маленьких, точечных изменениях, а не на глобальных модификациях.
• Упрощай или удаляй код: ищи возможности для упрощения логики или удаления ненужных фрагментов.
• Пиши эффективные docstrings: четко объясняй, что делает твой код, и давай ссылки на соответствующие ресурсы.
• Избегай лишних зависимостей: добавляй зависимости, только если они абсолютно необходимы.

Рис. 4. Лучшие практики документирования исходного кода.

Также важно учитывать долгосрочную поддержку кодовой базы. Перед внесением изменений спроси себя, не сломают ли они существующий код других пользователей Ultralytics. Если это возможно, подумай, как решить проблему и сделать правки максимально совместимыми.

Когда ты разработал код для внесения, его нужно протестировать. Ты можешь использовать фреймворки типа pytest для тестирования правок перед отправкой. Согласованное форматирование кода — еще один важный аспект. Инструменты вроде Ruff Formatter помогут поддерживать единый стиль и обнаружить логические ошибки или несоответствия в коде.

Link to this sectionПроверка pull request#

Проверка pull request (PR) — отличный способ внести вклад! PR создается, когда кто-то предлагает объединить свои изменения с основным проектом. Это помогает поддерживать стабильную работу проекта Ultralytics. При проверке PR убедись, что понимаешь, зачем были сделаны изменения. Автор должен четко объяснить цель и преимущества обновления, а ты должен увидеть доказательства тщательного тестирования в их PR.

Рис. 5. Что такое pull request?

Давай разберем несколько ключевых моментов, на которых стоит сосредоточиться.

• Проверь наличие юнит-тестов: убедись, что PR включает тесты для новых функций или изменений, чтобы подтвердить работоспособность кода и отсутствие проблем.
• Просмотри обновления документации: убедись, что документация отражает изменения или новые функции, включая примеры, API-справочники и другие детали.
• Оцени влияние на производительность: подумай, как изменения влияют на быстродействие. При необходимости запроси результаты тестирования производительности или дополнительную проверку.
• Проверь CI тесты: удостоверься, что все тесты Continuous Integration (CI) проходят успешно, включая проверки форматирования кода и результатов юнит-тестов.
• Сотрудничай при исправлении: если какой-то тест не проходит, работай совместно с автором, чтобы устранить ошибки до принятия PR.

Как ревьюер обязательно предоставляй конкретную и понятную обратную связь по любым вопросам или опасениям. Предлагай улучшения и задавай вопросы, которые помогут автору продумать потенциальные проблемы. Поощряй следование лучшим практикам в написании кода, тестировании и документации — и не стесняйся направлять их к ресурсам, которые могут помочь. Наконец, всегда признавай усилия автора. Положительная обратная связь помогает поддерживать дружелюбную и совместную атмосферу в open-source сообществе.

Link to this sectionВклад — это про сообщество#

Участие в open-source проектах, таких как Ultralytics, может дать тебе вдохновляющее чувство общности. Пишешь ли ты код, проверяешь PR, обновляешь документацию или участвуешь в дискуссиях — каждое усилие помогает проекту расти и развиваться. Ответы на вопросы или общение на GitHub, Discord, Subreddit или других форумах — ценный способ внести вклад и пообщаться с единомышленниками. Помни: твой вклад, даже самый маленький, оказывает значительное влияние и помогает создать атмосферу сотрудничества и поддержки для всех участников!

В Ultralytics мы стремимся внедрять инновации в open-source сообщество. Будь в курсе наших последних разработок, посещая наш репозиторий на GitHub. Присоединяйся к нашему яркому сообществу и посмотри, как мы влияем на такие отрасли, как сельское хозяйство и производство.