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

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

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

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

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

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

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

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

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

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

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

I have read the CLA Document and I sign the CLA

✍️ Документные строки Google

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

Примеры документальных строк

Google-стильGoogle-стиль с подсказками типаОднострочный

Этот пример иллюстрирует документальную строку в стиле Google. Убедитесь, что входные и выходные данные types всегда заключаются в круглые скобки, например, (bool).

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

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

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

✅ GitHub Actions CI Tests

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

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

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

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

👀 Просмотр запросов на исправление

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

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

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

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

Выберите точку отсчета:
- Форк Ultralytics YOLO: прямой форк репозиторияUltralytics YOLO , если сборка ведется на его основе.
- Используйте шаблон Ultralytics : Начните с репозитория шаблоновUltralytics , чтобы получить чистую, модульную установку, интегрирующую YOLO.
Лицензируйте свой проект:
- Добавить LICENSE файл, содержащий полный текст Лицензия AGPL-3.0.
- Добавьте уведомление в верхней части каждого исходного файла с указанием лицензии.
Опубликуйте свой исходный код:
- Сделайте свой весь исходный код проекта в открытом доступе (например, на GitHub). К ним относятся:
  - Полное крупное приложение или система, в которой реализована модель или код YOLO .
  - Любые изменения, внесенные в оригинальный код Ultralytics YOLO .
  - Скрипты для обучения, проверки, вывода.
  - Вес модели при изменении или доработке.
  - Конфигурационные файлы, настройки среды (requirements.txt, Dockerfiles).
  - Код бэкенда и фронтенда, если это часть веб-приложения.
  - Любые измененные вами сторонние библиотеки.
  - Обучающие данные, если они необходимы для запуска/переобучения , и их можно распространять.
Документ "Ясно":
- Обновите свой 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 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 ?

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

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

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

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