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

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

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

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

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

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

1. Сделай форк репозитория: Начни с создания форка соответствующего репозитория Ultralytics (например, ultralytics/ultralytics) в свой аккаунт GitHub.
2. Создай ветку: Создай новую ветку в своем форкнутом репозитории с понятным, описательным названием, отражающим твои изменения (например, fix-issue-123, add-feature-xyz).
3. Внеси свои изменения: Реализуй свои улучшения или исправления. Убедись, что твой код соответствует правилам оформления проекта и не привносит новых ошибок или предупреждений.
4. Протестируй изменения: Перед отправкой протестируй изменения локально, чтобы убедиться, что они работают как ожидалось и не вызывают регрессий. Добавь тесты, если ты внедряешь новую функциональность.
5. Commit your changes: Commit your changes with concise and descriptive commit messages. If your changes address a specific issue, include the issue number (e.g., Fix #123: Corrected calculation error.).
6. Создай pull request: Отправь pull request из своей ветки в ветку main оригинального репозитория Ultralytics. Укажи четкий заголовок и подробное описание цели и объема внесенных изменений.

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

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

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

✍️ Docstrings в стиле Google

При добавлении новых функций или классов используй docstrings в стиле 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

✅ Тесты CI через GitHub Actions

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

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

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

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

👀 Проверка Pull Requests

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

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

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

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

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

📜 Лицензия

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

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

🌍 Распространение твоего проекта YOLO под AGPL-3.0

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

Почему важна комплаенс с AGPL-3.0

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

Если ты предпочитаешь не открывать исходный код своего проекта, рассмотри возможность приобретения корпоративной лицензии (Enterprise License).

Как соблюдать 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, поддерживая open-source экосистему, которая делает возможными такие мощные инструменты, как Ultralytics YOLO.

Заключение

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

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

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

Почему мне стоит вносить вклад в open-source репозитории Ultralytics YOLO?

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

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

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

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

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

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

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

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

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

Чтобы сообщить об ошибке, приложи к отчету четкий и краткий Minimum Reproducible Example. Это поможет разработчикам быстро выявить и исправить проблему. Убедись, что твой пример минимален, но достаточен для воспроизведения проблемы. Более подробные инструкции по сообщению об ошибках см. в разделе Reporting Bugs.

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

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