Советы для начала работы над проектами 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 предлагает несколько способов принять участие, и ты можешь выбрать подходящий с учетом своих навыков и интересов.

Вот несколько вариантов:

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

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

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

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

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

При написании или редактировании помни, что для единообразия важно следовать рекомендациям проекта. Вот несколько советов по форматированию:

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

Рис. 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. Присоединяйся к нашему активному сообществу и узнай, как мы меняем такие отрасли, как сельское хозяйство и производство.