Вклад в проекты Ultralytics с открытым исходным кодом
Спасибо, что рассматриваешь возможность внести вклад в наши проекты Ultralytics с открытым исходным кодом. Твоё участие не только помогает повысить качество наших репозиториев, но и приносит пользу всему сообществу компьютерного зрения. В этом руководстве собраны понятные рекомендации и лучшие практики, которые помогут тебе начать.
Смотри: Как внести вклад в репозиторий Ultralytics | Модели, наборы данных и документация Ultralytics 🚀
Кодекс поведения#
Чтобы создать дружелюбную и открытую для всех атмосферу, каждый участник должен соблюдать наш Кодекс поведения. Уважение, доброжелательность и профессионализм — основа нашего сообщества.
Вклад через pull request#
Мы высоко ценим вклад в виде pull request (PR). Чтобы проверка прошла как можно проще, выполни следующие шаги:
- Создай форк репозитория: сначала создай форк нужного репозитория Ultralytics (например, ultralytics/ultralytics) в своём аккаунте GitHub.
- Создай ветку: создай новую ветку в своём форке и дай ей понятное описательное имя, отражающее изменения (например,
fix-issue-123,add-feature-xyz). - Внеси изменения: добавь улучшения или исправления. Убедись, что код соответствует правилам оформления проекта и не вызывает новых ошибок или предупреждений.
- Проверь свои изменения: Перед отправкой проверь изменения локально, чтобы убедиться, что они работают как ожидается и не вызывают регрессий. Существующие тесты охватывают большинство изменений, поэтому новые тесты часто не нужны; если новый тест полезен, предпочти добавить несколько строк в существующий файл тестов, а не писать тесты с моками.
- Зафиксируй изменения: создай коммит с кратким и понятным сообщением. Если изменения связаны с конкретной задачей, укажи её номер (например,
Fix #123: Corrected calculation error.). - Создай 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)).
В этом примере показан стандартный формат докстроки в стиле 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Тесты CI в GitHub Actions#
Перед слиянием все pull request должны пройти тесты GitHub Actions для непрерывной интеграции (CI). Эти тесты включают линтинг, модульные тесты и другие проверки, которые гарантируют, что изменения соответствуют стандартам качества проекта. Просмотри результаты CI и исправь обнаруженные проблемы.
Лучшие практики при внесении изменений в код#
Внося изменения в код проектов Ultralytics, придерживайся следующих рекомендаций:
- Избегай дублирования кода: по возможности повторно используй существующий код и своди число необязательных аргументов к минимуму.
- Вноси небольшие и целенаправленные изменения: сосредоточься на конкретных правках, а не на масштабных изменениях.
- Упрощай, когда это возможно: ищи способы упростить код или удалить лишние части.
- Учитывай совместимость: прежде чем вносить изменения, подумай, не нарушат ли они работу существующего кода с Ultralytics.
- Соблюдай единый стиль форматирования: такие инструменты, как Ruff Formatter, помогают поддерживать единообразный стиль.
Проверка pull request#
Проверка pull request — ещё один полезный способ внести вклад. Проверяя PR:
- Проверь обновления документации: убедись, что документация обновлена с учётом изменений.
- Оцени влияние на производительность: подумай, как изменения могут повлиять на производительность.
- Проверь тесты CI: убедись, что все тесты непрерывной интеграции проходят.
- Давай конструктивную обратную связь: конкретно и ясно указывай на проблемы и опасения.
- Отмечай приложенные усилия: признавай вклад автора, чтобы поддерживать позитивную атмосферу сотрудничества.
Сообщение об ошибках#
Мы очень ценим сообщения об ошибках: они помогают нам повышать качество и надежность проектов. При сообщении об ошибке через GitHub Issues:
- Проверь существующие задачи: сначала поищи, не сообщал ли кто-нибудь уже об этой ошибке.
- Приведи минимальный воспроизводимый пример: создай небольшой автономный фрагмент кода, который стабильно воспроизводит проблему. Это крайне важно для эффективной отладки.
- Опиши окружение: укажи операционную систему, версию Python, версии соответствующих библиотек (например,
torch,ultralytics) и оборудование (CPU/GPU. - Объясни, что должно было произойти и что произошло на самом деле: четко укажи ожидаемое и фактическое поведение. Приведи сообщения об ошибках и трассировки стека.
Лицензия#
Для своих репозиториев Ultralytics использует Стандартную общественную лицензию GNU Афферо версии 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.
-
Выбери, с чего начать:
- Создай форк Ultralytics YOLO: если собираешься тесно опираться на проект, создай форк репозитория Ultralytics YOLO.
- Используй шаблон Ultralytics: начни с репозитория-шаблона Ultralytics, чтобы получить чистую модульную основу с интеграцией YOLO.
-
Лицензируй свой проект:
- Добавь файл
LICENSEс полным текстом лицензии AGPL-3.0. - Добавь в начало каждого исходного файла уведомление о лицензии.
- Добавь файл
-
Опубликуй исходный код:
- Сделай весь исходный код проекта общедоступным (например, на GitHub). В него входят:
- Полное крупное приложение или система, включающие модель или код YOLO.
- Любые изменения, внесенные в исходный код Ultralytics YOLO.
- Скрипты для обучения, валидации и инференса.
- Веса модели, если они изменены или дообучены.
- Файлы конфигурации, настройки окружения (
requirements.txt,Dockerfiles. - Код бэкенда и фронтенда, если он входит в состав веб-приложения.
- Любые измененные тобой сторонние библиотеки.
- Обучающие данные, если они необходимы для запуска или повторного обучения и допускают распространение.
- Сделай весь исходный код проекта общедоступным (например, на GitHub). В него входят:
-
Документируй проект:
- Обнови
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 с открытым исходным кодом. Твой вклад помогает развивать наше ПО и сообщество — будь то улучшение кода, сообщения об ошибках или предложения новых функций.
Мы ценим твою готовность развивать технологии обнаружения объектов и будем рады твоему вкладу.
Часто задаваемые вопросы#
Вклад в репозитории Ultralytics YOLO с открытым исходным кодом улучшает программное обеспечение, делая его надежнее и функциональнее для всего сообщества. Можно улучшать код, исправлять ошибки, дорабатывать документацию и добавлять новые функции. Кроме того, ты сможешь сотрудничать с опытными разработчиками и экспертами в этой области, развивая собственные навыки и укрепляя профессиональную репутацию. О том, с чего начать, см. раздел Внесение изменений через запросы на слияние.
Чтобы подписать Соглашение участника о лицензировании (CLA), следуй инструкциям бота CLA после отправки запроса на слияние. Эта процедура гарантирует, что твой вклад будет надлежащим образом лицензирован по AGPL-3.0, сохраняя юридическую целостность проекта с открытым исходным кодом. Добавь в запрос на слияние комментарий:
I have read the CLA Document and I sign the CLAПодробнее см. в разделе Подписание CLA.
Документационные строки в стиле Google обеспечивают ясное и краткое описание функций и классов, повышая читаемость и удобство сопровождения кода. В них описываются назначение функции, аргументы и возвращаемые значения в соответствии с определенными правилами форматирования. При внесении вклада в Ultralytics YOLO использование документационных строк в стиле Google помогает хорошо документировать изменения и делает их понятными. Примеры и рекомендации см. в разделе Документационные строки в стиле Google.
Перед слиянием запроса на слияние он должен пройти все тесты Непрерывной интеграции (CI) в GitHub Actions. Эти тесты включают линтеры, модульные тесты и другие проверки, позволяющие убедиться, что код соответствует стандартам качества проекта. Изучи результаты CI и исправь все проблемы. Подробную информацию о процессе CI и советы по устранению неполадок см. в разделе CI-тесты GitHub Actions.
Чтобы сообщить об ошибке, приложи к сообщению четкий и краткий минимальный воспроизводимый пример. Это поможет разработчикам быстро выявить и устранить проблему. Пример должен быть минимальным, но достаточным для воспроизведения проблемы. Подробные инструкции по сообщению об ошибках см. в разделе Сообщение об ошибках.
Если ты используешь код или модели Ultralytics YOLO (распространяемые по лицензии AGPL-3.0) в своем проекте, лицензия AGPL-3.0 требует, чтобы весь проект (производный продукт) также распространялся по лицензии AGPL-3.0, а его полный исходный код был общедоступен. Это позволяет сохранять открытый характер программного обеспечения во всех производных продуктах. Если ты не можешь выполнить эти требования, нужно получить корпоративную лицензию. Подробности см. в разделе Открытая публикация проекта.
Комментарии7
Задай вопрос, поделись результатами или помоги кому-нибудь.
Mehrab-Shahbazi
Hi I will be happy if yolo add a feature that use slding window object detection. i want to add it and pull request it. is it usefull feature? will you accebt it?(if the tests passes).
Mehrab-Shahbazi
by sliding window, i mean crop big images ti smaller tiles and at the end merge all results as one output.( it is usefull for big images as you know)
Glenn JocherUltralytics@Mehrab-Shahbazi thank you for your interest in contributing! Sliding window object detection for large images can indeed be useful. If implemented efficiently and the tests pass, we welcome your pull request for review. Please ensure the feature aligns with the repository's design principles. For guidance, refer to our contributing guide.
Mehrab-Shahbazi
thank for your reply
esssyjr
Good evening all. I am trying to make a contribution for the dataset. I have forked and created a new branch but I could not see the folder specified for dataset. Should I just submit the .zip file to the root together with the read me, and send a pull request? Also, in my Github desktop I am unable to see Jupyter notebook as a code editor, but I manage to open the ultralytics cloned file in jupyter notebook, and uploaded the dataset. is that a good practice? Sorry for silly questions, I am new to open source contibution.
Glenn JocherUltralytics@esssyjr thank you for your interest in contributing! For dataset contributions, please follow the Ultralytics Contribution Guide and submit your dataset in a directory with a clear structure, including
train/andval/folders as applicable. Place the README in the same directory. Regarding Jupyter Notebook, it's fine to use it for preparing your dataset, but ensure your final submission is in the proper format per the guidelines. If you have more questions, feel free to ask on GitHub.esssyjr
Thanks for the reply, I have successfully uploaded the zip and readme file in the a folder in root of the Ultralytics repository. I requested a pull request in which it pass all the test but merge have been blocked, waiting for a approve review. Thank YOU
