Step-by-step contributor guide

This is a guide for contributors who want to add a new feature to the project. It explains how to fork the project, how to create a new branch, how to run the tests, how to add documentation, and how to submit a pull request.

1. Ensure git is installed on your system.

On Linux and Mac git comes pre-installed. On Windows, you can install git from:

• Git for windows

2. Fork the project

The first step to contributing is to fork the project on Github. This creates your own copy of the project that you can edit. To fork the project, you can click the “Fork” button on the project page or click here.

3. Clone the repository

The next step is to clone the repository to your local machine. To do this, you can run the following command:

git clone https://github.com/username/CUQIpy.git

where username is your Github username.

Then enter the repository

cd cuqipy

4. Create a virtual environment (optional)

It is recommended to create a virtual environment for the project. This allows you to install the project dependencies without affecting other projects on your system.

Using conda (recommended)

conda create -n cuqipy-dev
conda activate cuqipy-dev

Using virtualenv

python -m venv cuqipy-dev
source cuqipy-dev/bin/activate

5. Install the package in editable mode

To install the package in editable mode, run the following command:

pip install -e .

This will install the package so that any changes you make to the code will be reflected automatically reflected in the installed package.

6. Install developer dependencies

To run tests or build the documentation, you will need to install the developer dependencies. To do this, run the following command:

pip install -r requirements-dev.txt

7. Run the tests

To ensure that the package is working correctly, you should run the tests. To do this, run the following command:

python -m pytest -v

After making changes to the code, you should run the tests again to ensure that the changes have not broken anything.

8. Create a new branch for your changes.

Using git, you can create a new branch for your changes. This allows you to make changes without affecting the main code base. To create a new branch, run the following command:

git checkout -b my-changes

This creates a new branch named my-changes` and switches to it.

9. Make your changes to the code.

Now you can make your changes to the code.

You can get an overview of the changes by running:

git status

You can see the diff of the changes by running:

git diff

10. Commit your changes.

It is recommended commit your changes regularly. See the resource Git Guides - Git Commit for more information.

For example if you fixed a typo in the file cuqi/distribution/_distribution.py, you can commit it by running:

git add cuqi/distribution/_distribution.py
git commit -m "Fixed typo in distribution"

Please provide a meaningful commit message.

Keep repeating the two previous steps until you are happy with your changes.

11. Push your changes to the repository.

Once you are satisfied with your changes, you can push the my-changes branch to the repository.

git push origin my-changes

12. Submit a pull request.

After pushing your changes to the repository, it is time to submit a pull request.

Tip

A pull request is a request to merge your code into the main code-base. After pushing your changes they still live in a separate branch and need to be reviewed before they are merged into the main code-base.

The easiest way to submit a pull request is to use the link provided by git after you have pushed your changes. The message looks like this

remote: To create a pull request for 'my-changes', visit:
remote:   https://github.com/CUQI-DTU/username/pull/new/my-changes

where username is your Github username.

Alternatively you can submit a pull request by going to the project page on Github and clicking the “Pull requests” button.

Please provide a description of your changes and a link to the issue you are addressing.

13. Add reviewer to the pull request.

After you have submitted a t, you should add one of the core developers as a reviewer.

14. Wait for your pull request to be reviewed.

Once you have submitted a pull request, it will be reviewed by one of the project maintainers. If there are any issues with your pull request, you will be notified and asked to make changes.

If your pull request is accepted, it will be merged into the main code-base.

For more information on the git workflow see Git Guide.