CONTRIBUTING.md

Contributing

We appreciate all kinds of help, so thank you!

Code contribution guide

This guide is for those who want to extend the module or documentation. If you just want to use the package, read this other guide instead.

Code in this repository should conform to PEP8 standards. Style/lint checks are run to validate this. Line length must be limited to no more than 100 characters.

Initial set-up and installing dependencies

In order to contribute, you will need to install the module from source. If you do not have write permissions to the original Entanglement Forging repo, you will need to fork it to your personal account first, and submit all Pull Requests (PR) from there. Even if you have write permissions, forking the repo should always work, so this is the recommended approach.

Running tests

If you haven't already, install the repo in editable mode and with developer dependencies:

pip install -e .[dev]

To run tests:

tox -e{env}

where you replace {env} with py37, py38 or py39 depending on which version of python you have (to check python version, type python --version in the terminal).

To run linting tests (checks formatting/syntax):

tox -elint

To run notebook tests (for more info, see here):

treon docs/

Note: notebook tests check for execution and time-out errors, not correctness.

Making a pull request

Step-by-step

1. To make a contribution, first set up a remote branch (here called my-contribution) either in your fork (i.e. origin) or the original repo (i.e. upstream). In the absence of a fork, the (only) remote will simply be referred to all the time by the name origin (i.e. replace upstream in all commands):

   git checkout main
   git pull origin
   git checkout -b my-contribution
   

   ... make your contribution now (edit some code, add some files) ...

   git add .
   git commit -m 'initial working version of my contribution'
   git push -u origin my-contribution
   

2. Before making a Pull Request always get the latest changes from main (upstream if there is a fork, origin otherwise):

   git checkout main
   git pull upstream
   git checkout my-contribution
   git merge main
   

   ... fix any merge conflicts here ...

   git add .
   git commit -m 'merged updates from main'
   git push
   

3. Go back to the appropriate Entanglement Forging repo on GitHub (i.e. fork or original), switch to your contribution branch (same name: my-contribution), and click "Pull Request". Write a clear explanation of the feature.
4. Under Reviewer, select Aggie Branczyk and Caleb Johnson.
5. Click "Create Pull Request".
6. Your Pull Request will be reviewed and, if everything is ok, it will be merged.

Pull request checklist

When submitting a pull request and you feel it is ready for review, please ensure that:

1. The code follows the code style of this project and
2. successfully passes the unit tests.

Entanglement Forging uses Pylint and PEP8 style guidelines. For this you can run:

tox -elint

Other ways of contributing

Other than submitting new source code, users can contribute in the following meaningful ways:

• Reporting Bugs and Requesting Features: Users are encouraged to use Github Issues for reporting issues are requesting features.
• Ask/Answer Questions and Discuss Entanglement Forging: Users are encouraged to use Github Discussions for engaging with researchers, developers, and other users regarding this project.