Вклад в проекты с открытым исходным кодом Ultralytics

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

Смотреть: Как внести вклад в репозиторий Ultralytics | Модели, наборы данных и документация Ultralytics 🚀

Кодекс поведения

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

Вклад через Pull Requests

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

1. Форк репозитория: Начните с форка репозитория Ultralytics YOLO на свою учетную запись GitHub.

2. Создайте ветку: Создайте новую ветку в репозитории с форком с понятным, описательным именем, отражающим ваши изменения.

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

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

5. Зафиксируйте свои изменения: Зафиксируйте свои изменения с помощью краткого и описательного сообщения о фиксации. Если ваши изменения касаются конкретной проблемы, укажите номер проблемы в сообщении о фиксации.

6. Создайте запрос на притяжение: Отправьте запрос на исправление (pull request) из вашего форк-репозитория в основной репозиторий Ultralytics YOLO . Предоставьте четкое и подробное объяснение ваших изменений и того, как они улучшают проект.

Подписание CLA

Прежде чем мы сможем объединить ваш запрос, вы должны подписать наше Лицензионное соглашение с вкладчиком (CLA). Это юридическое соглашение гарантирует, что ваш вклад должным образом лицензирован, что позволяет проекту продолжать распространяться под лицензией AGPL-3.0 .

После отправки вашего запроса на выгрузку бот CLA проведет вас через процесс подписания. Чтобы подписать CLA, просто добавьте комментарий в свой PR, указав:

I have read the CLA Document and I sign the CLA

Google-Стиль Docstrings

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

def example_function(arg1, arg2=4):
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument, with a default value of 4.

    Returns:
        (bool): True if successful, False otherwise.

    Examples:
        >>> result = example_function(1, 2)  # returns False
    """
    if arg1 == arg2:
        return True
    return False

def example_function(arg1: int, arg2: int = 4) -> bool:
    """
    Example function demonstrating Google-style docstrings.

    Args:
        arg1: The first argument.
        arg2: The second argument, with a default value of 4.

    Returns:
        True if successful, False otherwise.

    Examples:
        >>> result = example_function(1, 2)  # returns False
    """
    if arg1 == arg2:
        return True
    return False

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

CI-тесты GitHub Actions

Все запросы на внесение изменений должны пройти тесты непрерывной интеграции (CI) GitHub Actions, прежде чем они будут объединены. Эти тесты включают в себя линтинг, модульные тесты и другие проверки, чтобы убедиться, что ваши изменения соответствуют стандартам качества проекта. Просмотрите результаты CI и решите все возникающие проблемы.

Лучшие практики по внесению кода

При внесении кода в проекты Ultralytics помните об этих лучших практиках:

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

Просмотр запросов на поставку

Рецензирование запросов на исправление - еще один ценный способ внести свой вклад. При рассмотрении PR:

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

Сообщение об ошибках

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

Лицензия

Ultralytics использует GNU Affero General Public License v3.0 (AGPL-3.0 ) для своих репозиториев. Эта лицензия способствует открытости, прозрачности и совместному совершенствованию при разработке программного обеспечения. Она гарантирует, что все пользователи могут свободно использовать, изменять и распространять программное обеспечение, способствуя созданию сильного сообщества для сотрудничества и инноваций.

Мы рекомендуем всем участникам ознакомиться с условиями лицензии AGPL-3.0 , чтобы вносить эффективный и этичный вклад в сообщество Ultralytics с открытым исходным кодом.

Открытые проекты с соблюдением требований YOLO и AGPL-3.0

Если вы планируете разработать и выпустить свой собственный проект, использующий модели YOLO , Стандартная общественная лицензия GNU Affero v3.0 (AGPL-3.0 ) гарантирует, что все производные работы останутся открытыми и доступными. В этом разделе приведены рекомендации, включая шаги, лучшие практики и требования, которые помогут вам открыть свой проект, соблюдая требования AGPL-3.0.

Варианты начала проекта

Вы можете начать свой проект, используя один из этих подходов:

1. Форк репозитория Ultralytics YOLO
   Форк официального репозитория Ultralytics YOLO непосредственно с сайта ultralytics
   

   • Используйте эту опцию, если вы планируете строить непосредственно на последней версии YOLO .
   • Вносите изменения в код форка по мере необходимости, обеспечивая при этом соблюдение AGPL-3.0.

2. Начните с репозитория шаблонов Ultralytics
   Используйте репозиторий шаблонов Ultralytics , доступный по адресу ultralytics
   

   • Идеально подходит для запуска чистого, модульного проекта с предварительно настроенными лучшими практиками.
   • Этот вариант обеспечивает легкую отправную точку для проектов, интегрирующих или расширяющих модели YOLO .

Что нужно для открытого исходного кода

Чтобы соответствовать требованиям AGPL-3.0, вы должны сделать открытыми следующие компоненты вашего проекта:

1. Весь исходный код вашего проекта:

   • Включите весь код большого проекта, содержащего ваши модели, скрипты и утилиты YOLO .

2. Вес модели (если она изменена):

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

3. Файлы конфигурации:

   • Предоставьте файлы конфигурации, такие как .yaml или .json которые определяют настройки обучения, гиперпараметры или конфигурации развертывания.

4. Учебные данные (если они распространяются):

   • Если вы включаете предварительно обработанные или сгенерированные данные, которые могут быть распространены, убедитесь, что они являются частью репозитория или имеют четкую ссылку.

5. Компоненты веб-приложений:

   • Включите весь исходный код бэкенда и фронтенда, если ваш проект представляет собой веб-приложение, особенно компоненты серверной части.

6. Документация:

   • Включите четкую документацию по использованию, сборке и расширению вашего проекта.

7. Сценарии сборки и развертывания:

   • Поделитесь сценариями для настройки среды, создания приложения и его развертывания, например Dockerfiles, requirements.txt, или Makefiles.

8. Система тестирования:

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

9. Модификации третьих лиц:

   • Предоставьте исходный код всех сторонних библиотек, которые вы изменили.

Шаги к открытому исходному коду вашего проекта

1. Выберите точку отсчета:

   • Форк репозитория Ultralytics YOLO или запуск из репозитория шаблонов Ultralytics .

2. Установите лицензию:

   • Добавить LICENSE файл, содержащий текст AGPL-3.0 .

3. Кредит "Вклад в развитие":

   • Укажите в своем README авторство Ultralytics YOLO . Например:

     This project builds on [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.
     

4. Сделайте свой код общедоступным:

   • Разместите весь проект (включая перечисленные выше компоненты) в публичном репозитории GitHub.

5. Документируйте свой проект:

   • Напишите четкий README.md с инструкциями по настройке, использованию и внесению вкладов.

6. Включить вклад:

   • Создайте трекер проблем и рекомендации по внесению вкладов, чтобы способствовать сотрудничеству.

Следуя этим шагам и обеспечивая включение всех необходимых компонентов, вы будете соблюдать AGPL-3.0 и вносить значимый вклад в сообщество разработчиков открытого кода. Давайте вместе продолжать развивать сотрудничество и инновации в области компьютерного зрения! 🚀

Пример структуры репозитория

Ниже приведен пример структуры проекта AGPL-3.0 . Подробности см. на сайте https://github.com/ultralytics /template.

my-yolo-project/
│
├── LICENSE               # AGPL-3.0 license text
├── README.md             # Project overview and license information
├── src/                  # Source code for the project
│   ├── model.py          # YOLO-based model implementation
│   ├── utils.py          # Utility scripts
│   └── ...
├── pyproject.toml        # Python dependencies
├── tests/                # Unit and integration tests
├── .github/              # GitHub Actions for CI
│   └── workflows/
│       └── ci.yml        # Continuous integration configuration
└── docs/                 # Project documentation
    └── index.md

Следуя этому руководству, вы сможете обеспечить соответствие вашего проекта требованиям AGPL-3.0 , внося при этом свой вклад в сообщество разработчиков открытого кода. Ваше следование этому принципу укрепляет этику сотрудничества, прозрачности и доступности, которая способствует успеху таких проектов, как YOLO.

Заключение

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

Мы с нетерпением ждем, когда ваши идеи воплотятся в жизнь, и ценим ваше стремление развивать технологию обнаружения объектов. Давайте вместе продолжать развиваться и внедрять инновации в этом захватывающем путешествии с открытым исходным кодом. Счастливого кодинга! 🚀🌟

ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ

Почему я должен вносить свой вклад в репозитории с открытым исходным кодом Ultralytics YOLO ?

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

Как подписать лицензионное соглашение с разработчиком (CLA) для Ultralytics YOLO ?

Чтобы подписать Лицензионное соглашение с контрибьютором (CLA), следуйте инструкциям, предоставленным CLA-ботом после отправки запроса на исправление. Этот процесс гарантирует, что ваш вклад будет должным образом лицензирован в соответствии с лицензией AGPL-3.0 , поддерживая юридическую целостность проекта с открытым исходным кодом. Добавьте комментарий в свой запрос на исправление, указав:

I have read the CLA Document and I sign the CLA

Дополнительные сведения см. в разделе Подписание CLA.

Что такое Google-style docstrings, и почему они требуются для Ultralytics YOLO вкладов?

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

Как я могу убедиться, что мои изменения прошли тесты GitHub Actions CI?

Перед тем как ваш запрос на слияние, он должен пройти все тесты непрерывной интеграции (CI) GitHub Actions. Эти тесты включают в себя линтинг, модульные тесты и другие проверки, чтобы убедиться, что код соответствует стандартам качества проекта. Просмотрите результаты CI и устраните все проблемы. Подробную информацию о процессе CI и советы по устранению неполадок можно найти в разделе Тесты CI в GitHub Actions.

Как сообщить об ошибке в репозиториях Ultralytics YOLO ?

Чтобы сообщить об ошибке, предоставьте вместе с сообщением об ошибке четкий и ясный минимальный воспроизводимый пример. Это поможет разработчикам быстро выявить и устранить проблему. Убедитесь, что ваш пример минимален, но достаточен для воспроизведения проблемы. Более подробные шаги по сообщению об ошибках приведены в разделе " Сообщение об ошибках".

📅 Создано 1 год назад ✏️ Обновлено 8 дней назад

Комментарии