98 строки
4.0 KiB
Markdown
98 строки
4.0 KiB
Markdown
# 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.
|