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

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

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

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

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

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

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

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

Отличная отправная точка — ознакомиться с official Ultralytics contributing guide. В нем собраны лучшие практики и советы, которые помогут тебе извлечь максимум пользы из твоего вклада. Первый шаг — ознакомиться с тем, что уже входит в проект, изучив contributing guidelines и погрузившись в код.

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

Если тебе нужна помощь, our quickstart guide содержит все необходимое для плавного старта.

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

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

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

• Documentation: Вклад в документацию — отличный способ погрузиться в проект и одновременно оттачить свои навыки письма. Ты можешь помочь, улучшая существующую документацию, добавляя недостающие детали или создавая новые руководства, которые облегчают участие другим.
• Bug fixes: Если у тебя есть опыт программирования, попробуй заняться исправлением багов. Это могут быть как мелкие правки, так и более сложные задачи, что позволит тебе внести реальный вклад в проект.
• Feature enhancements: Для тех, кто готов погрузиться глубже, работа над улучшением функций может быть одновременно сложной и интересной. Это может включать добавление новых функций, улучшение существующих или работу над дорожной картой проекта.
• Pull request reviews: Ревью PR — еще один ценный способ внести свой вклад, особенно если ты знаком со стандартами и лучшими практиками проекта. Оставляя отзывы и предлагая улучшения, ты помогаешь поддерживать качество и целостность кодовой базы.
• Community discussions: Участие в обсуждениях сообщества — отличный способ внести свой вклад, если тебе нравится сотрудничать и делиться идеями. Участвуй в текущих беседах, предлагай новые идеи или помогай другим, делясь своими мыслями и решениями.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Проверка pull request#

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

Fig 5. Что такое pull request?

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

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

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

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

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

В Ultralytics мы увлечены развитием инноваций в сообществе открытого исходного кода. Будь в курсе наших последних разработок, посещая наш GitHub repository. Присоединяйся к our vibrant community и посмотри, как мы влияем на такие отрасти, как agriculture и manufacturing.