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

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

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

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

Вклад через pull request#

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

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

Установка для разработки#

Клонируй свой форк (или основной репозиторий) и установи его в редактируемом режиме (-e), чтобы Python запускал локальные файлы и подхватывал все изменения без повторной установки:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Чтобы использовать форк в другом проекте вместо пакета PyPI, укажи для pip или requirements.txt ветку форка:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Изменения в документации#

Исходные файлы документации находятся в docs/en/. В корне репозитория установи зависимости для разработки и выполни полную строгую проверку перед созданием PR:

uv pip install -e ".[dev]"
python docs/build_docs.py

Перед запуском zensical build --strict проверка подготавливает сгенерированные справочные материалы, макросы и страницы сравнения. Чтобы быстрее просматривать страницы, в которых не используются макросы, запусти zensical serve.

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

Прежде чем мы сможем принять твой pull request, ты должен подписать наше Лицензионное соглашение участника (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

Тесты CI в GitHub Actions#

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

Лучшие практики при внесении изменений в код#

Внося изменения в код проектов Ultralytics, придерживайся следующих рекомендаций:

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

Проверка pull request#

Проверка pull request — ещё один полезный способ внести вклад. Проверяя PR:

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

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

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

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

Лицензия#

В своих репозиториях Ultralytics использует Стандартную общественную лицензию GNU Affero версии 3.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.

Заключение#

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

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

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