|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We'd love to accept your patches and contributions to this project. When contributing to the repository, please make sure to first discuss the changes you wish to make via a [github issue](https://github.com/adaptive-intelligent-robotics/QDax/issues). |
| 4 | + |
| 5 | +After the issue is discussed and the solution is determined, you will be invited to fork the repository and create a branch to implement the solution. Once ready to be merged, you can create a [Pull Request](https://github.com/adaptive-intelligent-robotics/QDax/pulls) on github and request to merge into the branch **develop**. |
| 6 | + |
| 7 | +When implementing your contribution, there are just a few guidelines you need to follow. |
| 8 | + |
| 9 | + |
| 10 | +## Installing Pre-commit hooks |
| 11 | + |
| 12 | +Pre-commits hooks have been configured for this project using the [pre-commit](https://pre-commit.com/) library: |
| 13 | + |
| 14 | +- [black](https://github.com/psf/black) python formatter |
| 15 | +- [flake8](https://flake8.pycqa.org/en/latest/) python linter |
| 16 | +- [isort](https://pypi.org/project/isort/) sorts imports |
| 17 | +- [nbstripout](https://github.com/kynan/nbstripout) strips outputs from notebooks |
| 18 | +- [mypy](https://github.com/pre-commit/mirrors-mypy) checks type hints |
| 19 | + |
| 20 | +To get them going on your side, make sure to have python installed, and run the following |
| 21 | +commands from the root directory of this repository: |
| 22 | + |
| 23 | +```bash |
| 24 | +pip install pre-commit |
| 25 | +pre-commit install |
| 26 | +``` |
| 27 | + |
| 28 | +You can then run the pre-commit hooks on all files as follows: |
| 29 | + |
| 30 | +```bash |
| 31 | +pre-commit run --all-files |
| 32 | +``` |
| 33 | + |
| 34 | + |
| 35 | +## Coding conventions |
| 36 | + |
| 37 | +Please respect the following conventions to contribute to the code: |
| 38 | + |
| 39 | +- Use hard wrap at 88 |
| 40 | +- Respect black, isort and flake8 conventions |
| 41 | +- Classes' names are Caml case (example: MyClass) |
| 42 | +- Functions and variables are in lower case with _ as separator (example: my_function, my_var) |
| 43 | +- Names are explicit: avoid mathematical notations, functions' names start with a verb |
| 44 | +- Use python typing library: each class and method should be typed (both for inputs and outputs) |
| 45 | +- Create custom types if needed |
| 46 | +- All classes and functions should have a docstring |
| 47 | +- Avoid repeating arguments and returns in docstring (should be explicit with the types) except when it is truly necessary |
| 48 | +- A function (or a class) does not take more than 5 arguments, if you need more create a data class |
| 49 | +- Avoid dictionaries to pass arguments when possible and prefer dataclasses instead |
| 50 | +- Repeat inputs names when calling a function: ex: compute_custom(arg1=arg1, arg2=my_arg2) |
| 51 | +- Use list comprehension when it is possible |
| 52 | +- Use f strings to add variables in strings: ex: print(f'my var value is {my_var}') |
| 53 | + |
| 54 | + |
| 55 | +## Commit messages |
| 56 | + |
| 57 | +Please try to follow the conventional [commit standard](https://www.conventionalcommits.org/en/v1.0.0/). |
| 58 | + |
| 59 | + |
| 60 | +## Merge request and code reviews |
| 61 | + |
| 62 | +All submissions, including submissions by project members, require review. We |
| 63 | +use GitHub pull requests for this purpose. Consult |
| 64 | +[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more |
| 65 | +information on using pull requests. |
| 66 | + |
| 67 | + |
| 68 | +## Community Guidelines |
| 69 | + |
| 70 | +This project follows |
| 71 | +[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). |
0 commit comments