How to Contribute

We would appreciate seeing you contributing to PyExperimenter. If you have any new idea or have found a bug, please first make sure to check the existing GitHub Issues. In case someone else have had a similar idea or has found the same bug, you could give further feedback on how to improve. Otherwise, please create an according issue. You are planning to work on this issue yourself, or you have found another issue you would like to work on? Great! Directly create a comment stating what exactly you are planning to do and setup the development workflow.

At the end, please make sure that you also extended the unit tests and that all unit tests are working correctly. Additionally, please update the documentation according to your changes. At the very end, create a pull request and mention the issue on which the changes are based, which contains important information for the review.

Setup Development Workflow

The development workflow for the PyExperimenter is based on the fork-and-branch git workflow as described in this blog post. The general steps are as follows:

Fork the GitHub repository: Log into GitHub, go to the PyExperimenter GitHub repository and click on Fork button in the top right corner.
Clone your GitHub repository fork: On your local machine, go into the folder where you want to clone the repository and clone your fork using the following command, but please ensure to replace <username>.
```
git clone https://github.com/<username>/py_experimenter.git
```
Add PyExperimenter remote: Add the original PyExperimenter repository as additional remote.
```
git remote add upstream https://github.com/tornede/py_experimenter.git
```
Create branch: Make sure that all branches are locally available and switch to the develop branch. Then create a new branch for your changes, but please ensure to replace <feature_branch_name> with some meaningful name.
```
git fetch --all
git branch -v -a
git switch develop
git checkout -b <feature_branch_name>
```

Create an environment for the development, e.g. using Anaconda.

conda create -n py-experimenter-env python=3.9
conda activate py-experimenter-env

Install the development dependencies using poetry.
```
poetry install
```
Make sure to install pandoc separately in your anaconda environment as this article suggests.
```
conda install pandoc
```
Check tests: Before working on any changes, please make sure that all unit tests are working correctly. Therefore, navigate into the git project folder and execute all unit tests.
```
pytest
```
Note

In case some tests are not succeeding due to ValueError of numpy, try to update that dependency manually and execute the tests again.
```
pip install numpy --upgrade
```
Finally you can start working on the planned changes! At any time, you can push your changes to the origin remote.

git push origin <feature_branch_name>

Extend Unit Tests

To provide a good usability of the PyExperimenter it is mandatory to extend and update the unit tests for all changes. The tests are located in the test folder of the project, using the same folder structure than the actual code. Additionally, it is important to execute all unit tests to ensure no other functionality has been affected. Therefore, navigate into the git project folder and execute all unit tests.

pytest

All tests except one should will succeed without any adaptions. But the test for the mysql provider needs credentials to a mysql database.

test/test_run_experiments/test_run_mysql_experiment.py

If you have a mysql database available, create a database credential file with the according information and execute the tests again. This time, all tests should succeed without further adaptions.

Update Documentation

The documentation of the PyExperimenter is key to all users to understand the functionality and the usability. Therefore, the documentation should be updated according to the changes. It is located in the docs folder of the project. Please check that the documentation can be built by first generating it locally. Therefore, navigate into the git project folder and execute sphinx. The builded website can be found in the project folder output/documentation/.

sphinx-build -b html docs/source/ output/documentation/

Create Pull Request

After all changes are made, including tests and documentation, make sure to commit and push all your changes.

Afterwards, go to the PyExperimenter GitHub Pull Requests and create a new pull request.

Make sure to select the correct source and destination repositories and according branches. The source repository is your fork, and the source branch is the <feature_branch_name>. The destination repository is tornede/py_experimenter and the destination branch is develop.
Provide a full description of the changes you did.
Reference the according issue you either created or have selected at the very beginning.