Руководство по внесению вклада в Gym

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

• Отчёты об ошибках (учтите, что изменение поведения среды должно быть сведено к минимуму, так как это требует выпуска новой версии среды и затрудняет сравнение результатов между версиями).
• Запросы на включение исправлений ошибок.
• Улучшения документации.

Особенно отметим, что мы не принимаем следующие виды вкладов:

• Новые среды.
• Новые функции.

Это может измениться в будущем. Если вы хотите создать среду Gym, следуйте инструкциям в разделе «Создание сред» (https://github.com/openai/gym/blob/master/docs/creating_environments.md). Когда ваша среда заработает, вы можете сделать PR, чтобы добавить её в конец списка сред (https://github.com/openai/gym/blob/master/docs/third_party_environments.md).

Редактировать 27 июля 2021 года: Пожалуйста, ознакомьтесь с https://github.com/openai/gym/issues/2259 для новых стандартов внесения вклада.

Разработка

Этот раздел содержит технические инструкции и советы для участников.

Проверка типов

Проект использует pyright для проверки типов. Чтобы выполнить проверку типов локально, установите pyright, следуя официальным инструкциям (https://github.com/microsoft/pyright#command-line). Его конфигурация находится в pyproject.toml. Она включает список включённых и исключённых файлов, которые в настоящее время поддерживают проверку типов. Чтобы запустить pyright для проекта, запустите процесс предварительной фиксации (pre-commit run --all-files) или pyright --project=pyproject.toml. Кроме того, pyright является встроенной функцией VSCode, которая автоматически предоставляет подсказки типов.

Добавление типизации к большему количеству модулей и пакетов

Если вы хотите добавить типизацию к модулю в проекте, список включённых, исключённых и строгих файлов можно найти в pyproject.toml (pyproject.toml -> [tool.pyright]). Чтобы запустить pyright для проекта, запустите процесс предварительной фиксации (pre-commit run --all-files) или pyright.

Git-хуки

CI будет выполнять несколько проверок нового кода, отправленного в репозиторий Gym. Эти проверки также можно выполнить локально без ожидания CI, выполнив следующие шаги:

1. Установите pre-commit (https://pre-commit.com/#install).
2. Установите Git-хуки, запустив pre-commit install.

После выполнения этих двух шагов Git-хуки будут запускаться автоматически при каждом новом коммите. Git-хуки также можно запустить вручную с помощью pre-commit run --all-files, а при необходимости их можно пропустить (не рекомендуется) с помощью git commit --no-verify. Примечание: возможно, вам придётся запустить pre-commit run --all-files вручную пару раз, чтобы он прошёл при фиксации, поскольку каждый инструмент форматирования сначала отформатирует код и потерпит неудачу в первый раз, но должен пройти во второй раз.

Кроме того, для запросов на вытягивание проект выполняет ряд тестов для всего проекта с использованием pytest (https://docs.pytest.org/en/latest/getting-started.html#install-pytest). Эти тесты можно запустить локально с помощью pytest в корневой папке.

Docstrings

Pydocstyle был добавлен в процесс предварительной фиксации, так что все новые функции следуют стилю docstring Google (https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). Все новые функции требуют либо короткой docstring, однострочного объяснения цели функции, либо многострочной docstring, документирующей каждый аргумент и тип возвращаемого значения функции (если таковой имеется). Кроме того, новый файл и класс требуют верхних docstrings, которые должны описывать цель файла/класса. Для классов примеры кода могут быть предоставлены в верхней docstring, а не в аргументах конструктора.

Чтобы проверить правильность ваших docstrings, запустите pre-commit run --all-files или pydocstyle --source --explain --convention=google. Если все docstrings терпят неудачу, предоставляется источник и причина неудачи.