How to contribute

First of all: thank you for considering to contribute to PyRigi!

PyRigi is licensed under MIT. By contributing to PyRigi:

  • you agree to license the code to which you contributed under PyRigi’s license terms;

  • you guarantee that your contribution does not infringe any license or copyright.

This page provides basic information to start contributing.

Communication

We use a Zulip chat for the communication among contributors. If you want to get access to it, please send an email to this address. Feel free to ask any questions regarding PyRigi in a Zulip channel.

You can come with your own ideas on what to develop or you can check the channel To be implemented for some suggestions about what the maintainers would be happy to have in PyRigi.

Important

Currently, we prefer the following contributions to the code:

  • resolving an existing TODO (especially adding examples and tests),

  • implementing a method marked as Waiting for implementation or returning NotImplementedError,

  • or adding missing definitions.

Git(flow)

We use Git for version control and the project is hosted at Github. We use Gitflow (see also this description) for PyRigi development. In a nutshell, this means that there are two prominent branches in PyRigi’s Git repository:

  • main, which contains the stable version of the package

  • dev, which is used for the development.

Collaborators are not allowed to push their Git commits directly to these two branches. Rather, they should employ pull requests. Say Alice and Bob want to implement feature X in PyRigi. These are the tasks to be performed:

  1. they branch from dev, creating a branch called feature-X, and there they develop the intended functionality;

  2. once they are done, they push feature-X to GitHub and solicit a pull request of feature-X into dev;

  3. the code is checked by the maintainers, who may ask some other collaborator to serve as reviewer; in this process, comments and suggested of change may be sent to Alice and Bob until agreement is reached about the feature and the pull request receives approval;

  4. a maintainer merges feature-X into dev.

We propose a few categories for contributing branches:

  • features: branches to implement new features/improvements to the current status; their name should start by feature-

  • documentation: branches to modify the documentation; their name should start by doc-

  • bugs: branches to solve known bugs; their name should start by bug-

  • hotfix: branches to solve an urgent error; their name should start by hotfix-

  • testing: branches to add tests; their name should start by test-

  • refactoring: branches to refactor the code; their name should start by refactor-

Once in a while, the maintainers merge the branch dev into main and create a new release. The release numbers follow this scheme:

  • MAJOR version: significant functionality extensions yielding possibly incompatible API changes (x+1.y.z)

  • MINOR version: new functionality in a backward compatible manner (x.y+1.z)

  • PATCH version: backward compatible bug fixes (x.y.z+1).

Code

Dependencies

We maintain the dependencies of the package using Poetry. See the installation instructions.

To install the package dependencies including those needed for the development, run

poetry install --no-root

in the root folder of PyRigi. Omitting --no-root installs also PyRigi itself, so it can be used system-wide. Poetry installs the dependencies and the package to a virtual environment. To activate this environment, run poetry shell. You can exit it with exit or Ctrl+D.

If you want to install dependencies necessary only for the package itself, not for the development, run

poetry install --only main

PEP8

We follow PEP8 indications regarding Python code format.

To check whether the code is PEP8-compliant, we strongly suggest to use flake8. To check your code, simply run

flake8

in PyRigi’s home folder (with poetry shell activated). The .flake8 file in PyRigi’s home folder, which specifies flake8 configuration, is the same that is used in the automatic tests once a pull request is filed in GitHub. Therefore, please check your code with flake8 before performing a pull request.

There are tools that format code according to PEP8 indications. We strongly suggest to use black. To format your code, run

black .

in the root folder (with poetry shell activated) to modify the files in place. We suggest to integrate the use of black at every commit as explained at this page of black’s guide.

The lines in the source code can be at most 90 characters long. The only exceptions are lines in docstrings that might be longer due to long output in an example or a reference. To avoid checking them by the automatic tests for pull requests, use noqa like this:

"""
veeeeery long docstring that has to violate the 90 characters limit due to a reference or an example
"""  # noqa: E501

Testing

Tests are extremely important to guarantee the realiability of code. Please create tests for the functionalities that you implement and place them in the test folder, within the appropriate file. Each test should be in the form of a method starting with test_. Tests can be parametrized, see for instance test_inf_rigid in test_framework.py.

Moreover, please add a section EXAMPLES in the docstring of the classes and methods that you introduce and provide there examples of the functionalities you implemented.

Please keep in mind that whenever a pull request is opened, all the tests in the testfolder and in the docstrings are run. Therefore, before opening a pull request we strongly advise to run

pytest --doctest-modules

in the root folder of PyRigi (with poetry shell activated). The reason why the examples in the docstrings are tested is to make sure their outputs are valid, they do not replace the tests in the test folder.

Documentation

We aim to have the package well-documented. Since the main purpose of the package is mathematical research, it requires rigorous definitions. Hence, an essential part of the documentation is the mathematical background.

The documentation is generated from docstrings using Sphinx. We use the theme Furo. The docstrings are written in reST, formatted according to numpydoc and parsed using napoleon to retrieve the information from type hinting. The other documentation source files are written in MyST (see also the cheatsheet). The following extensions are used:

These are already installed if you used poetry install.

To compile, run Sphinx in the folder doc (with poetry shell activated) by:

make html

or

make latexpdf

Docstrings

For an example how a docstring should look like, see for instance the docstring of Framework or Framework.realization(). In general, a docstring should contain the following items (in this order):

  • short description (one line, compulsory)

  • longer description (optional)

  • list of definitions (optional)

  • parameters description (optional): types are added automatically from type hinting

  • examples (highly recommended)

  • notes (optional): implementation details

Auto-build

If you want that the documentation folder is kept watched and documentation is automatically rebuilt once a change is detected (works only for .md files, not docstrings), you can use the Sphinx extension sphinx-autobuild. Run in the doc folder (with poetry shell activated):

sphinx-autobuild . _build/html --open-browser

To recompile everything, stop the previous command and run

make clean
make html

Cleaning is necessary especially to get the documentation updated after a change in docstrings.

Creating tutorials

We appreciate a lot if you can contribute with a notebook that illustrates how to use PyRigi, describes a rigidity theory problem, accompanies a paper etc.

The tutorials section is generated from Jupyter notebooks; more precisely, from MyST Markdown mirrors of .ipynb notebooks. This allows versioning the .md notebooks in Git without having troubles with the metadata, outputs etc. of .ipynb notebooks. The pairing of .ipynb notebooks with MyST .md notebooks is achieved using Jupytext.

Please, do not commit the .ipynb to the repository. You can contact a maintainer if you have a .ipynb tutorial you want to contribute but struggle to get its .md version.

In case poetry shell is used as described above, Jupyterlab and Jupytext can be install using

pip install jupyterlab jupytext

After setting the virtual enviroment in Jupyterlab to the one created by poetry shell, .md notebooks can be opened directly.