|
| 1 | +# Gym Contribution Guidelines |
| 2 | + |
| 3 | +At this time we are currently accepting the current forms of contributions: |
| 4 | + |
| 5 | +- Bug reports (keep in mind that changing environment behavior should be minimized as that requires releasing a new version of the environment and makes results hard to compare across versions) |
| 6 | +- Pull requests for bug fixes |
| 7 | +- Documentation improvements |
| 8 | + |
| 9 | +Notably, we are not accepting these forms of contributions: |
| 10 | + |
| 11 | +- New environments |
| 12 | +- New features |
| 13 | + |
| 14 | +This may change in the future. |
| 15 | +If you wish to make a Gym environment, follow the instructions in [Creating Environments](https://github.com/openai/gym/blob/master/docs/creating_environments.md). When your environment works, you can make a PR to add it to the bottom of the [List of Environments](https://github.com/openai/gym/blob/master/docs/third_party_environments.md). |
| 16 | + |
| 17 | + |
| 18 | +Edit July 27, 2021: Please see https://github.com/openai/gym/issues/2259 for new contributing standards |
| 19 | + |
| 20 | +# Development |
| 21 | +This section contains technical instructions & hints for the contributors. |
| 22 | + |
| 23 | +## Type checking |
| 24 | +The project uses `pyright` to check types. |
| 25 | +To type check locally, install `pyright` per official [instructions](https://github.com/microsoft/pyright#command-line). |
| 26 | +It's configuration lives within `pyproject.toml`. It includes list of included and excluded files currently supporting type checks. |
| 27 | +To run `pyright` for the project, run the pre-commit process (`pre-commit run --all-files`) or `pyright --project=pyproject.toml` |
| 28 | +Alternatively, pyright is a built-in feature of VSCode that will automatically provide type hinting. |
| 29 | + |
| 30 | +### Adding typing to more modules and packages |
| 31 | +If you would like to add typing to a module in the project, |
| 32 | +the list of included, excluded and strict files can be found in pyproject.toml (pyproject.toml -> [tool.pyright]). |
| 33 | +To run `pyright` for the project, run the pre-commit process (`pre-commit run --all-files`) or `pyright` |
| 34 | + |
| 35 | +## Git hooks |
| 36 | +The CI will run several checks on the new code pushed to the Gym repository. These checks can also be run locally without waiting for the CI by following the steps below: |
| 37 | +1. [install `pre-commit`](https://pre-commit.com/#install), |
| 38 | +2. Install the Git hooks by running `pre-commit install`. |
| 39 | + |
| 40 | +Once those two steps are done, the Git hooks will be run automatically at every new commit. |
| 41 | +The Git hooks can also be run manually with `pre-commit run --all-files`, and if needed they can be skipped (not recommended) with `git commit --no-verify`. |
| 42 | +**Note:** you may have to run `pre-commit run --all-files` manually a couple of times to make it pass when you commit, as each formatting tool will first format the code and fail the first time but should pass the second time. |
| 43 | + |
| 44 | +Additionally, for pull requests, the project runs a number of tests for the whole project using [pytest](https://docs.pytest.org/en/latest/getting-started.html#install-pytest). |
| 45 | +These tests can be run locally with `pytest` in the root folder. |
| 46 | + |
| 47 | +## Docstrings |
| 48 | +Pydocstyle has been added to the pre-commit process such that all new functions follow the [google docstring style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). |
| 49 | +All new functions require either a short docstring, a single line explaining the purpose of a function |
| 50 | +or a multiline docstring that documents each argument and the return type (if there is one) of the function. |
| 51 | +In addition, new file and class require top docstrings that should outline the purpose of the file/class. |
| 52 | +For classes, code block examples can be provided in the top docstring and not the constructor arguments. |
| 53 | + |
| 54 | +To check your docstrings are correct, run `pre-commit run --all-files` or `pydocstyle --source --explain --convention=google`. |
| 55 | +If all docstrings that fail, the source and reason for the failure is provided. |
0 commit comments