coach/CONTRIBUTING.md

# Contributing to Coach

The following is a set of guidelines for contributing to Coach.
We'd like Coach to be useful to students, data scientists and researchers, and the purpose of these guidelines is to help maintain a level of quality and reliability for the Coach users community. 
Thanks for taking the time to contribute!

## Proposing a PR
If you would like to make code changes to Coach, whether adding new functionality or fixing a bug, please make sure to follow this list:
1. Create a new [branch](https://help.github.com/articles/about-branches/) for your work (give it a short but meaningful name related to the functionality or bug you are working on), then add commits as necessary.  Once its in a reviewable state [open up a pull request](https://help.github.com/articles/about-pull-requests/)
1. Add unit tests to any new component, or update existing tests for modified component’s functionality
1. Make sure [regression tests](https://github.com/IntelLabs/coach/tree/master/rl_coach/tests) are passing. See the [Testing section](#testing) for more details on the Coach testing methodology 
1. Update documentation to reflect any API changes, or added algorithm or environment. See the [Documentation section](#documentation) for more details on Coach documentation. 
1. Adding an algorithm? 
    1. Please follow the guidelines [here](https://intellabs.github.io/coach/contributing/add_agent.html)
    1. Add a [benchmark](https://github.com/IntelLabs/coach/blob/master/benchmarks/README.md) showing the results match those of the relevant research paper
    1. Update the algorithms diagram (https://github.com/IntelLabs/coach/blob/master/docs_raw/source/diagrams.xml), export as png and update the README image (https://github.com/IntelLabs/coach/blob/master/img/algorithms.png) 
1. Adding an environment? 
    1. Please follow the guidelines here (https://intellabs.github.io/coach/contributing/add_env.html)
    1. (Nice to have) Create a preset of an agent solving that environment
1. Ensure your branch is up-to-date with latest master, and get your PR reviewed and merged.  Generally a reviewer will be assigned once one of the project maintainers notices a new PR (if it has been a couple of days and there hasn't been progress feel free to add a new comment or [email us](#contact)).  There may be some back and forth discussion or modifications required, but if a reviewer has approved your PR they will then squash your set of commits and merge it into the master branch.


## Filing an Issue
Before filing an issue, please make sure you:
1. Search through the [issues list](https://github.com/IntelLabs/coach/issues) to make sure a similar issue does not exist
1. Specify the following details:
    1. Setup - operating system, versions of installed environments or packages (if relevant), hardware details (if relevant)
    1. Use case description - command line, parameters
    
    We prioritize issues to P1/P2/P3 based on our understanding of their impact on the Coach users community. It would be helpful if you describe the exact impact of the issue if not fixed. 


## Testing
Coach uses the pytest framework for its tests. All tests are located in the [tests folder](https://github.com/IntelLabs/coach/tree/master/rl_coach/tests), and are divided to four categories - Unit, Integration, Golden and Trace tests.
Please refer to the tests [README](https://github.com/IntelLabs/coach/blob/master/rl_coach/tests/README.md) for the full details of the Coach testing methodology.
Before proposing any code changes to Coach please make sure any new functionality is tested, and that regression tests are passing. 

All pull request commits are automatically run through our unit and integration tests via our CI suite, the results of which are visible on the github PR page as well as the CircleCI [Coach test results page](https://circleci.com/gh/IntelLabs/coach).  Merges to the `master` branch are blocked until these tests pass.  Further end-to-end tests can optionally be run against these commits and are kicked off from the PR page by the assigned reviewer.


## Documentation
Most of Coach’s documentation is located on the [Coach GitHub Pages](https://intellabs.github.io/coach/). The pages contain information on Coach’s usage and features, design and components, and on how to add new agents or environments. 
Their content is located in the [docs](https://github.com/IntelLabs/coach/tree/master/docs) folder, which is built from the raw files under the [docs_raw](https://github.com/IntelLabs/coach/tree/master/docs_raw) folder. 
When making documentation changes, please modify the files in the docs_raw folder, and refer to the [README](https://github.com/IntelLabs/coach/blob/master/docs_raw/README.md) for instructions on how to build the docs folder. 
Both the docs_raw and docs folders need to be committed when documentation changes are made.  


## Releases
Coach is released as two pypi packages:

[rl-coach](https://pypi.org/project/rl-coach/) - contains the full tensorflow-based installation. Note that most environments require additional packages to be installed. We point to the relevant installation instructions in the [README](https://github.com/IntelLabs/coach#supported-environments).

[rl-coach-slim](https://pypi.org/project/rl-coach-slim/) - same as rl-coach, except for the deep learning framework (so user can use an already installed Tensorflow or MxNet framework, or explicitly state which one to install), and Kubernetes (for [distributed Coach](https://intellabs.github.io/coach/dist_usage.html)). 

Each pypi package release has a GitHub release and tag with the same version number. The numbers are of the X.Y.Z format, where

X - currently one, will be incremented on major API changes 

Y - major releases with new features

Z - maintenance releases with bug fixes


## Contact
You’re welcome to contact the Intel Coach team either by filing a GitHub issue, or at coach@intel.com