How to contribute#

Architecture Overview#

A high-level overview of the different modules in tqec is available in

Installation procedure (for developers)#

If you want to help maintaining and improving the tqec package, you will need to install a few more packages than the regular installation. It is also recommended to use an editable installation.

Currently, tqec is compatible with Python 3.10, 3.11, 3.12 and 3.13. You can install the editable version of tqec through pip or uv.

Hint

Creating an environment before running pip install is optional but recommended to avoid everything installing globally. Click here for a common approach.

# Clone the repository to have local files to work on
git clone https://github.com/tqec/tqec.git

# Go in the tqec directory
cd tqec

# Update pip to at least v25.1
python -m pip install --upgrade "pip>=25.1"

# Install developer dependencies
python -m pip install --group all
# Install tqec in editable mode (the "-e" option)
python -m pip install -e .
# enable pre-commit
pre-commit install

Attention

The -e option to the python -m pip install call is important as it installs an editable version of tqec. Without that option, changes made in the folder tqec will not be reflected on the tqec package installed.

Without the -e option, pip copies all the files it needs (mainly, the code) to the current Python package folder. Any modification to the original tqec folder you installed the package from will not be reflected automatically on the copied files, which will limit your ability to test new changes on the code base. The -e option tells pip to create a link instead of copying, which means that the code in the tqec folder will be the code used when importing tqec.

# Clone the repository to have local files to work on
git clone https://github.com/tqec/tqec.git
# Go in the tqec directory
cd tqec
# Install the library with developer dependencies
# Note the "-editable" option, that's important.
uv sync --group all
# enable pre-commit
uv run pre-commit install

Attention

Note that compared to pip, we do not need to explicitly provide a flag for an editable installation in uv. By default, uv sync will install an editable version of tqec. Without the editable installation, changes made in the folder tqec will not be reflected on the installed tqec package.

Without sync, uv copies all the files it needs (mainly, the code) to the current Python package folder. Any modification to the original tqec folder you installed the package from will not be reflected automatically on the copied files, which will limit your ability to test new changes on the code base.

Warning

You might have to install pandoc separately as the instructions above only install a pandoc wrapper, not the executable. See https://pandoc.org/installing.html for instructions.

If you encounter any issue during the installation, please refer to How to install tqec for more information.

You can now start contributing, following the rules explained in the next sections.

Install the documentation dependencies before building the docs:

python -m pip install --group docs

uv sync --group docs

If you also need the test dependencies, install both dependency groups:

python -m pip install --group docs --group test

uv sync --group docs --group test

Building documentation locally#

There are two ways to build the documentation locally:

Fast build (recommended for iterating on docs content)

Skips notebook execution and expensive examples. Significantly faster for quick feedback loops.

cd docs
make fasthtml

This build excludes: - The gallery examples (docs/gallery/*.ipynb) - Heavy simulation examples: quick_start, detailed_plots, collada_interop, build_computation, bgraph

Use this mode when editing documentation content, adding examples, or testing structure changes.

Full build (for final validation before opening a PR)

Executes all notebooks and examples. Produces the complete documentation with all outputs.

cd docs
make html

Use this mode to: - Validate that all examples run correctly - Check outputs and visualizations - Before opening a pull request

If make html or make fasthtml reports that a Sphinx extension cannot be imported, make sure the documentation dependencies were installed with uv sync --group docs from the repository root.

If you encounter unrelated warnings or issues during the build, consider opening an issue.

Contributing to documentation#

Executable examples are preferred over static code blocks when the example depends on the tqec API. Running these blocks during the documentation build helps us catch pages that have gone out of date after code changes.

Adding a page to the user guide#

User guide pages are written in reStructuredText and stored in docs/user_guide. To add a new page:

  1. Create a new .rst file in docs/user_guide.

  2. Add the page to the appropriate toctree in docs/user_guide/index.rst. This makes the page visible in the user guide navigation.

  3. Use .. jupyter-execute:: blocks for Python examples that should be run during the docs build.

  4. Put images and other page-specific media in a matching subdirectory under docs/media/user_guide when possible.

  5. If possible, build the documentation locally to verify your changes. Use make fasthtml for quick iteration, then make html before opening a PR to validate all examples run correctly.

Working with references#

The documentation uses sphinxcontrib-bibtex for references. Add new BibTeX entries to docs/refs.bib in alphabetical order by the first author’s last name. To cite an entry from a user guide page, use the footcite role:

:footcite:`CitationKey`

In a notebook markdown cell, use the equivalent HTML markup:

<cite data-footcite-t="CitationKey"></cite>

For additional guidance on writing mathematical notations and LaTeX in reStructuredText, see:

Pages and notebooks that use references should end with a references section:

References
----------

.. footbibliography::

How to contribute#

1. Look at issues#

Start by looking at the issues list. Issues can be filtered by tags. Below are a few of the most interesting tags:

  • good first issue for issues that have been judged easy to address without prior knowledge on the code base.

  • backend for issues related to the Python code.

Pick one issue that you want to work on. We emphasize on want: this is an open source project, so do not force yourself to work on something that does not interest you.

2. Comment on one or more issues#

Once you have found one or more issue(s) you want to work on, send a comment on these issues to:

  1. make your interest public,

  2. ask for updates, as the issue might not be up-to-date.

One of the lead developers will come back to you and assign you the issue if

  1. nobody is already working on it,

  2. the issue is still relevant.

3. Create a specific branch for each issue#

If you are a part of the tqec community, you will be able to create a branch directly in the tqec repository. If you are not, you can fork the tqec repository on your own account (click here) and create a branch there.

4. Work in your branch#

You should only work on the branch you just created. Implement the fix you envisioned to the issue you were assigned to.

To test your changes, start by running the “fast” tests in our test suite:

#!/usr/bin/env bash

uv run pytest

You may need to modify some of the existing tests to ensure they all pass. Likewise, if you create a new class/function, you’ll need to write new tests to support that. Look at the existing tests/ for examples.

To run the slower (integ) tests, run

#!/usr/bin/env bash

uv run pytest -m slow

Once all tests pass (reproducing the desired behavior) feel free to move on to the next step.

If, for personal/professional reasons, lack of motivation, lack of time, or whatever the reason for which you know that you won’t be able to complete your implementation, please let us know in the issue so that we can un-assign you and let someone else work on the issue.

5. Submit and merge a pull request#

Once you think you have something that is ready for review or at least ready to be read by other people, you can submit a pull request (PR) on the main branch of the tqec repository. In the PR message, try to provide as much information as possible to help other people understanding your code.

Once your code has been reviewed and accepted by at least one of the developers, the PR can be merged to the main branch.

For contributors with write access: you can merge the PR yourself by clicking the “Merge” button.

For external contributors (no write access): please add a comment on the PR indicating it is ready to merge (e.g., “Ready to merge” or “@maintainers ready to merge”), and a maintainer will merge it for you.