From fa1cb1b139bb294861b21698f721f5421c4386ab Mon Sep 17 00:00:00 2001
From: Purva Thakre <66048318+purva-thakre@users.noreply.github.com>
Date: Wed, 16 Jun 2021 04:38:52 -0500
Subject: [PATCH] Update contribution guidelines (#58)

Adds some information about running local tests, generating local code coverage and making sure new code is PEP8 compliant.
---
 README.md                        |  4 +-
 doc/source/contribution-code.rst | 79 ++++++++++++++++++++++++++++++--
 2 files changed, 78 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 7b255768..1368064b 100755
--- a/README.md
+++ b/README.md
@@ -43,12 +43,12 @@ If you want to edit the source code, please download the source code and run the
 pip install --upgrade pip
 pip install -e .
 ```
-which makes sure that you are up to date with the latest `pip` version.
+which makes sure that you are up to date with the latest `pip` version. Contribution guidelines are available [*here*](https://qutip-qip.readthedocs.io/en/latest/contribution-code.html). 
 
 To build and test the documentation, additional packages need to be installed:
 
 ```
-pip install matplotlib sphinx numpydoc sphinx_rtd_theme
+pip install pytest matplotlib sphinx numpydoc sphinx_rtd_theme
 ```
 
 Under the `doc` directory, use
diff --git a/doc/source/contribution-code.rst b/doc/source/contribution-code.rst
index 15618ccb..ed266c98 100644
--- a/doc/source/contribution-code.rst
+++ b/doc/source/contribution-code.rst
@@ -7,10 +7,10 @@ Contributing to the source code
 Build up an development environment
 ===================================
 
-Please follow the instruction on the `QuTiP contribution guide <https://qutip.org/docs/latest/development/contributing.html#building>`_ to 
+Please follow the instruction on the `QuTiP contribution guide <https://qutip.org/docs/latest/development/contributing.html#building>`_ to
 build a conda environment.
-You don't need to build `qutip` in the editable mode unless you also want to contribute to `qutip`.
-Instead, you need to install qutip-qip by downloading the source code and run
+You don't need to build ``qutip`` in the editable mode unless you also want to contribute to `qutip`.
+Instead, you need to install ``qutip-qip`` by downloading the source code and run
 
 .. code-block:: bash
 
@@ -24,3 +24,76 @@ explaining the functionality, including input parameters and returned values.
 The docstring should follow
 `NumPy Style Python Docstrings <https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html>`_.
 
+Checking Code Style and Format
+==============================
+
+In order to check if your code in ``some_file.py`` follows `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_
+style guidelines, `Black <https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_
+has to be installed.
+
+.. code-block::
+
+  pip install black
+
+In the directory that contains ``some_file.py``, use
+
+.. code-block::
+
+  black some_file.py --check
+  black some_file.py --diff --color
+  black some_file.py
+
+Using ``--check`` will show if any of the file will be reformatted or not.
+
+  * `Code 0 <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#the-basics>`_ means nothing will be reformatted.
+  * Code 1 means one or more files could be reformatted. More than one files could
+    be reformatted if ``black some_directory --check`` is used.
+
+Using ``--diff --color`` will show a `difference <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#diffs>`_ of
+the changes that will be made by ``Black``. If you would prefer these changes to be made, use the last line of above code block.
+
+.. note::
+  We are currently in the process of checking format of existing code in ``qutip-qip``.
+  Running ``black existing_file.py`` will attempt to format existing code. We
+  advise you to create a separate issue for ``existing_file.py`` or skip re-formatting
+  ``existing_file.py`` in the same PR as your new contribution.
+
+  It is advised to keep your new contribution ``PEP8`` compliant.
+
+Checking tests locally
+=======================
+
+You can run tests and generate code coverage report locally. First make sure
+required packages have been installed.
+
+.. code-block::
+
+  pip install pytest pytest-cov
+
+``pytest`` is used to test files containing tests. If you would like to test all the
+files contained in a directory then specify the path to this directory. In order to run
+tests in ``test_something.py`` then specify the exact path to this file for ``pytest``
+or navigate to the file before running the tests.
+
+.. code-block::
+
+  pytest path_to_some_directory
+  pytest /path_to_test_something/test_something.py
+  ~/path_to_test_something$ pytest test_something.py
+
+A code coverage report in ``html`` format  can be generated locally for
+``qutip-qip`` using the code line given below. By default the coverage report
+is generated in a temporary directory ``htmlcov``. The report can be output
+in `other formats <https://pytest-cov.readthedocs.io/en/latest/reporting.html>`_
+besides ``html``.
+
+.. code-block::
+
+  pytest --cov-report html --cov=qutip_qip tests/
+
+If you would prefer to check the code coverage of one specific file, specify
+the location of this file. Same as above the report can be accessed in ``htmlcov``.
+
+.. code-block::
+
+  pytest --cov-report html --cov=qutip_qip tests/test_something.py