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

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

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

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

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

🚀 Вклад через запросы на включение изменений

Мы высоко ценим вклад в виде запросов на внесение изменений (pull requests, PR). Чтобы максимально упростить процесс проверки, выполните следующие действия:

1. Сделайте форк репозитория: Начните с создания форка соответствующего репозитория Ultralytics (например, ultralytics/ultralytics) в свою учетную запись GitHub.
2. Создайте ветку: Создайте новую ветку в вашем форкнутом репозитории с четким, описательным именем, отражающим ваши изменения (например, fix-issue-123, add-feature-xyz).
3. Внесите свои изменения: Реализуйте свои улучшения или исправления. Убедитесь, что ваш код соответствует руководящим принципам стиля проекта и не вносит новых ошибок или предупреждений.
4. Проверьте свои изменения: Перед отправкой протестируйте свои изменения локально, чтобы убедиться, что они работают должным образом и не вызывают регрессий. Добавьте тесты, если вы добавляете новые функциональные возможности.
5. Зафиксируйте изменения: Фиксируйте свои изменения с помощью кратких и описательных сообщений коммитов. Если ваши изменения касаются конкретной проблемы, укажите номер проблемы (например, Fix #123: Corrected calculation error.).
6. Создайте запрос на включение внесенных изменений: Отправьте запрос на включение изменений из вашей ветки в main ветвь оригинального репозитория Ultralytics. Предоставьте четкое название и подробное описание, объясняющее цель и объем ваших изменений.

📝 Подписание CLA

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

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

I have read the CLA Document and I sign the CLA

✍️ Докстринги в стиле Google

При добавлении новых функций или классов, включите Строки документации в стиле Google для четкой, стандартизированной документации. Всегда заключайте как входные, так и выходные данные types в круглых скобках (например, (bool), (np.ndarray)).

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

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

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

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

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

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

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

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

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(1, 1)  # True
    """
    return arg1 == arg2

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

✅ CI-тесты GitHub Actions

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

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

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

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

👀 Рассмотрение запросов на включение изменений

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

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

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

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

• Проверьте существующие issues: Сначала поищите, чтобы узнать, не сообщалось ли уже об ошибке.
• Предоставьте Минимальный воспроизводимый пример: Создайте небольшой, автономный фрагмент кода, который последовательно воспроизводит проблему. Это крайне важно для эффективной отладки.
• Опишите окружение: Укажите вашу операционную систему, версию Python, соответствующие версии библиотек (например, torch, ultralytics), и оборудование (CPU/GPU).
• Объясните ожидаемое и фактическое поведение: Четко укажите, что вы ожидали увидеть и что произошло на самом деле. Укажите любые сообщения об ошибках или трассировки.

📜 Лицензия

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

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

🌍 Открытие исходного кода вашего проекта YOLO под лицензией AGPL-3.0

Используете модели или код Ultralytics YOLO в своем проекте? Лицензия AGPL-3.0 требует, чтобы вся ваша производная работа также была с открытым исходным кодом под AGPL-3.0. Это гарантирует, что модификации и более крупные проекты, построенные на основе открытого исходного кода, останутся открытыми.

Почему важна совместимость с AGPL-3.0

• Поддерживает открытое программное обеспечение: Обеспечивает, чтобы улучшения и производные работы приносили пользу сообществу.
• Юридическое требование: Использование кода, лицензированного AGPL-3.0, обязывает ваш проект соблюдать его условия.
• Содействие сотрудничеству: Поощряет обмен и прозрачность.

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

Как соблюдать требования AGPL-3.0

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

1. Выберите отправную точку:

   • Форк Ultralytics YOLO: Сделайте форк непосредственно репозитория Ultralytics YOLO, если строите на его основе.
   • Используйте шаблон Ultralytics: Начните с шаблонного репозитория Ultralytics для чистой, модульной настройки, интегрирующей YOLO.

2. Лицензирование вашего проекта:

   • Добавьте LICENSE файл, содержащий полный текст Лицензия AGPL-3.0.
   • Добавьте уведомление в верхней части каждого исходного файла, указывающее лицензию.

3. Опубликуйте свой исходный код:

   • Сделайте свой исходный код всего проекта общедоступны (например, на GitHub). Это включает:
     • Полное более крупное приложение или система, которая включает в себя модель или код YOLO.
     • Любые изменения, внесенные в оригинальный код Ultralytics YOLO.
     • Скрипты для обучения, валидации, инференса.
     • Веса модели в случае изменения или тонкой настройки.
     • Файлы конфигурации, настройки окружения (requirements.txt, Dockerfiles).
     • Код серверной и клиентской части, если это часть веб-приложения.
     • Любые измененные вами сторонние библиотеки.
     • Данные для обучения, если они необходимы для запуска / переобучения и распространения.

4. Четко документируйте:

   • Обновите свой README.md чтобы указать, что проект лицензирован в соответствии с AGPL-3.0.
   • Включите четкие инструкции по настройке, сборке и запуску вашего проекта из исходного кода.
   • Укажите Ultralytics YOLO соответствующим образом, ссылаясь на оригинальный репозиторий. Пример:

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

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

Практический пример структуры см. в шаблонном репозитории Ultralytics:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

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

🎉 Заключение

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

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

Часто задаваемые вопросы

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

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

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

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

I have read the CLA Document and I sign the CLA

Для получения дополнительной информации см. раздел Подписание CLA.

Что такое строки документации в стиле Google и почему они необходимы для вклада в Ultralytics YOLO?

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

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

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

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

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

Что означает лицензия AGPL-3.0, если я использую Ultralytics YOLO в своем проекте?

Если вы используете код или модели Ultralytics YOLO (лицензированные по AGPL-3.0) в своем проекте, лицензия AGPL-3.0 требует, чтобы весь ваш проект (производная работа) также был лицензирован по AGPL-3.0, и его полный исходный код должен быть общедоступным. Это гарантирует, что открытый характер программного обеспечения сохраняется во всех его производных. Если вы не можете выполнить эти требования, вам необходимо получить корпоративную лицензию Enterprise License. Подробности см. в разделе Open-Sourcing Your Project.

📅 Создано 1 год назад ✏️ Обновлено 1 месяц назад

Комментарии