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

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

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

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

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

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

Мы высоко ценим вклад в виде пулл-реквестов (PR). Чтобы сделать процесс проверки максимально плавным, выполни следующие шаги:

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

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

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

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

I have read the CLA Document and I sign the CLA

✍️ Google-Style Docstrings#

При добавлении новых функций или классов включай документацию в стиле Google для получения понятной и стандартизированной документации. Всегда заключай как входные, так и выходные 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

✅ Тесты GitHub Actions CI#

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

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

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

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

👀 Проверка pull requests#

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

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

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

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

Проверь существующие проблемы: Сначала выполни поиск, чтобы убедиться, что об ошибке еще не сообщали.
Предоставь минимальный воспроизводимый пример: Создай небольшой автономный фрагмент кода, который стабильно воспроизводит проблему. Это крайне важно для эффективной отладки.
Опиши окружение: Укажи свою операционную систему, версию 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.

Выбери свою отправную точку:
- Сделай форк 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.

Заключение#

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

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

FAQ#

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

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

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

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

I have read the CLA Document and I sign the CLA

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

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

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

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

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

Участники

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

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