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

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

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

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

Вклад через PR#

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

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

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

После отправки запроса на слияние бот 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#

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

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

Внося код в проекты Ultralytics, помни о следующих лучших практиках:

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

Рецензирование PR#

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

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

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

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

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

Заключение#

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

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

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