Внесение вклада в OpenMMLab

Добро пожаловать в сообщество MMCV, мы стремимся создать современную основу для компьютерного зрения и приветствуем все виды вкладов, включая, но не ограничиваясь следующими:

Исправление ошибок

Вы можете напрямую отправить запрос на слияние (Pull Request) для исправления опечаток в коде или документах.

Шаги по исправлению ошибок реализации кода следующие.

1. Если изменения затрагивают значительные части, вы должны сначала создать проблему (issue) и описать информацию об ошибке и способ её воспроизведения. Другие разработчики будут обсуждать это с вами и предлагать правильное решение.

2. После исправления ошибки отправьте запрос на слияние (pull request) и добавьте соответствующий юнит тест.

Новый функционал или улучшение

1. Если изменения затрагивают значительные части, вы должны создать проблему (issue) для обсуждения нового дизайна с нашими разработчиками.
2. После реализации нового функционала или улучшения отправьте запрос на слияние (pull request) и добавьте соответствующий юнит тест.

Документация

Вы можете напрямую отправить запрос на слияние (pull request) для исправления документов. Если вы хотите добавить новый документ, вам следует сначала создать проблему (issue) для проверки его целесообразности.### Процесс работы с запросами на слияние (Pull Requests)

Если вы ещё не знакомы с запросами на слияние, не волнуйтесь! Ниже представлен пошаговый гайд по созданию запроса на слияние. Если вы хотите углубиться в режим разработки запросов на слияние, вы можете обратиться к официальной документации.

1. Создание форка и клонирование

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

Затем вы можете клонировать репозиторий локально:

git clone git@github.com:{username}/mmcv.git

После этого вы должны добавить официальный репозиторий как upstream репозиторий

git remote add upstream git@github.com:open-mmlab/mmcv

Проверьте, успешно ли был добавлен удалённый репозиторий командой `git remote -v````bash origin git@github.com:{username}/mmcv.git (fetch) origin git@github.com:{username}/mmcv.git (push) upstream git@github.com:open-mmlab/mmcv (fetch) upstream git@github.com:open-mmlab/mmcv (push)

> Вот краткое введение в понятия "origin" и "upstream". Когда мы используем команду `git clone`, создается удалённый репозиторий с именем "origin", который указывает на клонируемый репозиторий. Что касается "upstream", то его мы добавляем самостоятельно, чтобы он указывал на целевой репозиторий. Конечно, если вам не нравится имя "upstream", вы можете называть его как хотите. Обычно мы отправляем код на "origin". Если отправленный код конфликтует с последними изменениями в официальном ("upstream") репозитории, нам следует получить последние изменения из "upstream" для решения конфликта, а затем снова отправить код на "origin". Отправленный Pull Request будет автоматически обновлен.#### 2. Настройка pre-commit

Вы должны настроить [pre-commit](https://pre-commit.com/#intro) в локальной среде разработки, чтобы убедиться, что стиль кода соответствует стандартам OpenMMLab. **Примечание:** следующие команды должны выполняться в директории MMCV.

```shell
pip install -U pre-commit
pre-commit install

Проверьте успешность настройки pre-commit и установите хуки, определенные в файле .pre-commit-config.yaml.

pre-commit run --all-files

Если процесс установки прерывается, можно повторно запустить pre-commit run ..., чтобы продолжить установку.

Если код не соответствует спецификациям стиля кода, pre-commit выдаст предупреждение и автоматически исправит некоторые ошибки.

Если мы хотим зафиксировать наш код, минуя хук pre-commit, можем использовать опцию --no-verify (только временно).

git commit -m "xxx" --no-verify

3. Создание ветки разработки

После настройки pre-commit следует создать ветку на основе основной ветки для реализации новой функциональности или исправления ошибок. Предложенное имя ветки — username/pr_name

git checkout -b username/pr_name
```В дальнейшем при разработке, если основная ветка локального репозитория отстает от основной ветки "upstream", нам потребуется получить последние изменения из "upstream" для синхронизации, а затем выполнить вышеуказанную команду.```shell
git pull upstream master
```### 4. Подтвердите изменения и пройдите юнит-тестирование

- MMCV использует mypy для статической проверки типов с целью повышения надёжности кода. Поэтому нам нужно добавить аннотации типов в наш код и пройти проверку mypy. Если вы не знакомы с аннотациями типов, вы можете обратиться к [этому руководству](https://docs.python.org/3/library/typing.html).

- Подтверждённый код должен пройти юнит-тестирование:

  ```shell
  # Пройти все юнит-тесты
  pytest tests

  # Пройти юнит-тесты запуска
  pytest tests/test_runner/test_runner.py

Если юнит-тесты провалились из-за отсутствия зависимостей, вы можете установить зависимости, следуя руководству.

• Если были изменены или добавлены документы, следует проверить результат их отображения, следуя руководству.

5. Отправьте код на удалённый сервер

После прохождения тестирования и проверки pre-commit можно отправить локальные коммиты на удалённый сервер. Вы можете связать локальную ветку с удалённой, добавив опцию -u.

git push -u origin {branch_name}

Это позволит вам использовать команду git push, чтобы отправлять код напрямую в следующий раз, не указывая имя ветки или удалённый репозиторий.

6. Создайте запрос на слияние

(1) Создайте запрос на слияние через интерфейс GitHub Pull Request

Примечание: Изображение вставлено без изменений, поскольку его содержание не требует перевода.(2) Измените описание запроса согласно рекомендациям, чтобы другие разработчики лучше понимали ваши изменения

Дополнительные детали описания запроса на слияние см. в руководстве по созданию запроса на слияние.

Примечание

(a) Описание запроса на слияние должно содержать причину изменения, его содержание и последствия, а также ссылаться на соответствующее Issue (см. документацию).

(b) Если это ваш первый вклад, пожалуйста, подпишите CLA

(c) Проверьте, проходит ли Pull Request через CI

MMCV выполнит юнит-тестирование отправленного Pull Request на различных платформах (Linux, Windows, Mac) с использованием разных версий Python, PyTorch и CUDA, чтобы убедиться в корректности кода. Вы можете просмотреть конкретную информацию о тестировании, нажав на Details в вышестоящем изображении и модифицировать код при необходимости.(3) Если Pull Request успешно пройдет через CI, то вы сможете ждать отзывов других разработчиков. На основе замечаний рецензента вы будете модифицировать код и повторять шаги 4-5 до тех пор, пока все рецензенты не одобрят изменения. После этого мы как можно скорее произведем слияние.

7. Разрешение конфликтов

Если ваш локальный ветвь сталкивается с конфликтом относительно последней версии основной ветки "upstream", вам потребуется разрешить эти конфликты. Есть два способа сделать это:

git fetch --all --prune
git rebase upstream/master

или

git fetch --all --prune
git merge upstream/master

Если вы хорошо знакомы с решением конфликтов, вы можете использовать rebase для решения конфликтов, так как это позволяет поддерживать чистоту вашего журнала коммитов. Если вы не знакомы с rebase, вы можете использовать merge для решения конфликтов.

Руководство

Юнит-тестирование

Если вы не можете запустить юнит-тестирование некоторых модулей из-за отсутствия зависимостей, таких как модуль video, вы можете попробовать установить следующие зависимости:

# Linux
sudo apt-get update -y
sudo apt-get install -y libturbojpeg
sudo apt-get install -y ffmpeg

# Windows
conda install ffmpeg

Мы также должны убедиться, что зафиксированный код не снижает покрытие юнит-тестами. Мы можем запустить следующую команду для проверки покрытия юнит-тестами:

python -m coverage run -m pytest /путь/к/файлу_теста
python -m coverage html
# проверьте файл в htmlcov/index.html

Генерация документовЕсли документы были изменены/добавлены, нам следует проверить результат генерации. Мы можем установить зависимости и запустить следующую команду для генерации документов и проверки результатов:

pip install -r requirements/docs.txt
cd docs/ru/
# или docs/en
make html
# проверьте файл в ./docs/ru/_build/html/index.html
```### Стиль кода

#### Python

Мы используем [PEP8](https://www.python.org/dev/peps/pep-0008/) как предпочитаемый стиль оформления кода.

Мы используем следующие инструменты для линтера и форматирования:

- [flake8](https://github.com/PyCQA/flake8): Обёртка вокруг некоторых инструментов для линтера.
- [isort](https://github.com/timothycrosley/isort): Утилита Python для сортировки импортов.
- [yapf](https://github.com/google/yapf): Форматтер для файлов Python.
- [codespell](https://github.com/codespell-project/codespell): Утилита Python для исправления распространённых опечаток в текстовых файлах.
- [mdformat](https://github.com/executablebooks/mdformat): Mdformat — это мнемонический форматтер Markdown, который можно использовать для обеспечения согласованного стиля в файлах Markdown.
- [docformatter](https://github.com/myint/docformatter): Форматтер для форматирования строки документации.

Конфигурации стилей yapf и isort находятся в [setup.cfg](./setup.cfg).

Мы используем [pre-commit hook](https://pre-commit.com/), который проверяет и форматирует для `flake8`, `yapf`, `isort`, пробелов в конце строк, файлов Markdown,
фиксирует конец файлов, двойные кавычки, pragma кодировки Python, смешанные окончания строк, автоматически сортирует `requirements.txt` при каждом коммите.
Конфиг pre-commit hook хранится в [.pre-commit-config](./.pre-commit-config.yaml).

#### C++ и CUDA

Мы следуем [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).

### Описание Pull Request

1. Используйте [pre-commit](https://pre-commit.com/) hook для предотвращения проблем со стилем кода.2. Одна временная ветка должна соответствовать только одному Pull Request.

3. Выполняйте подробные изменения в одном Pull Request. Избегайте больших Pull Requests.

   - Недопустимо: Поддержка Faster R-CNN
   - Принимается: Добавление головы коробки к Faster R-CNN
   - Отлично: Добавление параметра к голове коробки для поддержки пользовательского количества слоев свёртки

4. Предоставьте ясные и значимые сообщения коммитов.

5. Предоставьте ясное и содержательное описание Pull Request.

   - В названии задачи должно быть указано название. Общий формат: \[Префикс\] Краткое описание Pull Request (Постфикс)
   - Префикс: добавление новой функции \[Функциональность\], исправление ошибки \[Исправление\], связанное с документами \[Документация\], находится в разработке \[WIP\] (что временно не будет рассматриваться)
   - Введите основные изменения, результаты и влияние на другие модули в кратком описании
   - Связывайте связанные проблемы и pull requests с майлстоуном