Link to this sectionВклад в проекты с открытым исходным кодом 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.

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

Link to this section🤝 Кодекс поведения#

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

Link to this section🚀 Вклад через Pull Requests#

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

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

Link to this section📝 Подписание CLA#

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

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

I have read the CLA Document and I sign the CLA

Link to this section✍️ Google-Style Docstrings#

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

Примеры 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.

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

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

Link to this section✅ Тесты GitHub Actions CI#

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.

Link to this section✨ Лучшие практики для внесения вклада в код#

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

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

Link to this section👀 Проверка pull requests#

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

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

Link to this section🐞 Сообщение об ошибках#

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

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

Link to this section📜 Лицензия#

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

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

Link to this section🌍 Распространение твоего проекта YOLO с открытым исходным кодом под AGPL-3.0#

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

Link to this sectionПочему соблюдение AGPL-3.0 имеет значение#

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

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

Link to this sectionКак соблюдать AGPL-3.0#

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

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

Link to this sectionПример структуры репозитория#

Обратись к репозиторию-шаблону 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.

Link to this sectionЗаключение#

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.

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

Link to this sectionFAQ#

Link to this sectionПочему мне стоит участвовать в репозиториях Ultralytics YOLO с открытым исходным кодом?#

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

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

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

I have read the CLA Document and I sign the CLA

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

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

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

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

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

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

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

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

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

Участники

GLglenn-jocher²³ RIRizwanMunawar³ RAraimbekovm¹ PDpderrenger¹ Y-Y-T-G¹ WIWillieMaddox¹ LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

Создано 12 нояб. 2023 г.Обновлено 4 дня назад