QuTiP Development Guidelines

QuTiP Development Guidelines

Document status: work in progress

QuTiP is an open source project and we welcome contributions from anyone. All development takes place in our repositories on the qutip project page on github: https://github.com/qutip

There are many ways to get involved in working with QuTiP. For example:

• Reporting bugs, deficiencies in the documentation, providing ideas for new features, by creating issues on our issue tracker
• Answering questions and participating in discussions on the QuTiP forum: https://groups.google.com/forum/#!forum/qutip
• Contributing to the official documentation or our collection of examples scripts and notebooks
• Contributing code to the project (more info below).
• Test and code reviewing existing pull requests. Participate in the discussions about new features and changes in open pull requests.

All contributions are moderated by QuTiP core members: https://github.com/orgs/qutip/people

Contributing code to QuTiP

Workflow

When contributing to the source code of QuTiP, the documentation, or the example collections, we encourage following this workflow:

1. Create a fork of the corresponding repository on github.

2. Checkout and create a new branch in your forked repository:

    $ git clone https://github.com/username/qutip.git
    $ git checkout -b new-feature-name
   

3. Add the changes to the created branch and push it to your clone on github, and create a pull request to the official QuTiP repository. Please label the pull request (PR) with either the code or physics label (or both).

4. A core team member will be assigned to the pull request, and will be responsible for code reviewing and testing.

5. Everyone is encouraged to participate in the testing, code reviewing and discussion on any open pull request.

6. When a pull request is ready to be merged, it is flagged with the label 'review-merge-ready' and if there are no further code-review comments, the assigned core team member merges the pull request.

Coding style

All code in QuTiP should be:

• PEP8 compliant. PEP8 is a standard coding style. Please use the pep8 tool to check that code in pull requests that are submitted to QuTiP is correctly PEP8 formatted.
• Compatible with both Python 2.7 and Python 3+. We recommend having working environment for both Python 2 and 3 on your system, and that all unit tests passes locally before submitting a pull request or pushing commits to an existing pull request.
• New code must be covered by unit tests that are added to the qutip/tests directory.
• Preferably new features should be documented in an IPython notebook that demonstrates and explains how to use it. Such notebooks should be submitted to the qutip-notebooks repository.