Contributing#

Contributions to Disimpy are warmly welcomed.

If you want to discuss ideas before writing code, please open an issue on GitHub, and we’ll discuss how to continue. GitHub issues are also a great way to inform the developers about any bugs or problems you may encounter.

Development workflow#

If you already have a well-defined idea or want to make small changes (fix typos, improve documentation, etc.), please follow the steps below:

  1. Fork the repository on GitHub.

  2. Clone your fork:

git clone git@github.com:YOUR-USERNAME/disimpy.git

  1. Configure Git to sync your fork with the main repo:

git remote add upstream https://github.com/kerkelae/disimpy.git

  1. Create a branch with a name that describes your contribution:

git checkout -b BRANCH-NAME

  1. Write code, commit changes, and push to your fork on GitHub.

  2. Open a pull request on GitHub.

GitHub docs provide more information on forking a repository and creating pull requests.

Tip

When making changes to the code, it is recommended to use the conda environment in the file development_environment.yml and to install the package in editable mode by executing the following in the root directory of the repository:

pip install -e .

Code style#

All code should be formatted with Black using the default settings and documented following the Numpy docstring conventions (except trivial internal functions).

Tests#

It is important to make sure that your changes have not broken anything by running all tests:

from disimpy.tests import test_all
test_all()

Documentation#

If you make changes to the documentation, you should build it locally to confirm that it works as expected by executing the following in docs:

make clean
make html

This will generate a local copy of the documentation in docs/_build/html. Once the changes are merged with the master branch, the online documentation is automatically updated. Requirements for generating the documentation locally are listed in docs/requirements.txt, and they can be installed with pip:

pip install -r docs/requirements.txt