# Contribution Guidelines

Thank you for your interest in contributing to the ML-Agents Toolkit! We are
incredibly excited to see how members of our community will use and extend the
ML-Agents Toolkit. To facilitate your contributions, we've outlined a brief set
of guidelines to ensure that your extensions can be easily integrated.

## Communication

First, please read through our
[code of conduct](https://github.com/Unity-Technologies/ml-agents/blob/main/CODE_OF_CONDUCT.md),
as we expect all our contributors to follow it.

Second, before starting on a project that you intend to contribute to the
ML-Agents Toolkit (whether environments or modifications to the codebase), we
**strongly** recommend posting on our
[Issues page](https://github.com/Unity-Technologies/ml-agents/issues) and
briefly outlining the changes you plan to make. This will enable us to provide
some context that may be helpful for you. This could range from advice and
feedback on how to optimally perform your changes or reasons for not doing it.

Lastly, if you're looking for input on what to contribute, feel free to reach
out to us directly at ml-agents@unity3d.com and/or browse the GitHub issues with
the `Requests` or `Bug` label.

## Git Branches

The main branch corresponds to the most recent version of the project. Note
that this may be newer that the
[latest release](https://github.com/Unity-Technologies/ml-agents/releases/tag/latest_release).

When contributing to the project, please make sure that your Pull Request (PR)
contains the following:

- Detailed description of the changes performed
- Corresponding changes to documentation, unit tests and sample environments (if
  applicable)
- Summary of the tests performed to validate your changes
- Issue numbers that the PR resolves (if any)

## Environments

We are currently not accepting environment contributions directly into ML-Agents.
However, we believe community created enviornments have a lot of value to the
community. If you have an interesting enviornment and are willing to share,
feel free to showcase it and share any relevant files in the
[ML-Agents forum](https://forum.unity.com/forums/ml-agents.453/).

## Continuous Integration (CI)

We run continuous integration on all PRs; all tests must be passing before the PR is merged.

Several static checks are run on the codebase using the
[pre-commit framework](https://pre-commit.com/) during CI. To execute the same
checks locally, run:
```bash
pip install pre-commit>=2.8.0
pip install identify>==2.1.3
pre-commit run --all-files
```

Some hooks (for example, `black`) will output the corrected version of the code;
others (like `mypy`) may require more effort to fix. You can optionally run
`pre-commit install` to install it as a git hook; after this it will run on all
commits that you make.

### Code style

All python code should be formatted with
[`black`](https://github.com/psf/black).

C# code is formatted using [`dotnet-format`](https://github.com/dotnet/format).
You must have [dotnet](https://dotnet.microsoft.com/download) installed first
(but don't need to install `dotnet-format` - `pre-commit` will do that for you).

### Python type annotations

We use [`mypy`](http://mypy-lang.org/) to perform static type checking on python
code. Currently not all code is annotated but we will increase coverage over
time. If you are adding or refactoring code, please

1. Add type annotations to the new or refactored code.
2. Make sure that code calling or called by the modified code also has type
   annotations.

The
[type hint cheat sheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)
provides a good introduction to adding type hints.

## Contributor License Agreements

When you open a pull request, you will be asked to acknolwedge our Contributor
License Agreement. We allow both individual contributions and contributions made
on behalf of companies. We use an open source tool called CLA assistant. If you
have any questions on our CLA, please
[submit an issue](https://github.com/Unity-Technologies/ml-agents/issues) or
email us at ml-agents@unity3d.com.