Contributor guide#

This page explains how to contribute to tqec:

Contribution process#

The process below is maintained in CONTRIBUTING.md at the root of the repository and included here, so that GitHub and this page show the same text.

Ways to contribute#

  • Report a bug or request a feature. Open an issue with the matching template, and add the labels that fit.

  • Ask a question. Open an issue with the “Asking a question” template and give as much context as you can.

  • Contribute code or documentation. Follow the contribution steps below.

Issue labels#

Labels sort issues and pull requests by kind, topic and priority. The full list, with descriptions, is on the labels page. The ones most useful for finding work are:

Other labels give the kind of change (bug, enhancement, fix, refactor, performance, documentation, ci/cd) or the part of the project it touches (circuit-generation, block graph, hci, ux). Issues labelled on hold or future are blocked and are not ready to be picked up.

Contribution steps#

1. Find an issue#

Start with the issues list, and filter it by the labels above.

Pick an issue that captures your interest. This is an open source project. Do not force yourself to work on something that does not interest you.

Writing an issue#

If no issue describes the change you have in mind, create one before writing any code. Use the matching template and keep the issue short enough for a maintainer with limited time to read:

  • one problem or feature per issue;

  • a title that says what is wrong or what is wanted;

  • for a bug, say what happened, what you expected, and give the smallest code example that reproduces it;

  • for a feature, give the motivation and the alternatives you considered.

A bug report must include code that reproduces the bug, so that a maintainer can run it and see the problem.

2. Comment on the issue#

Comment on the issue to:

  1. make your interest public;

  2. ask whether the issue is still up to date.

A maintainer will assign the issue to you if nobody else is working on it and it is still relevant. Wait for the assignment before you start. This prevents two people from working on the same change without knowing about each other.

You claim an issue by commenting on it, and it is yours once a maintainer assigns it to you. The “Assignees” field of the issue shows who is working on it.

The first time you comment on an issue, an automated reply asks whether you are a human and how you used AI tools, and lists the account checks your account would fail on a pull request. Answer its questions in a reply. Until your first pull request is merged, ask to be assigned to one issue at a time; the reply reminds you if you already claim other open issues.

Working on an assigned issue#

Post short progress updates in the issue, especially when you are stuck or progress slows down. A draft pull request is a good way to show progress.

For some important, potentially advanced features, describe the advantages of your approach in the issue or PR.

If you find that you cannot finish, for whatever reason, say so in the issue so that a maintainer can remove your assignment and someone else can pick it up.

If someone else is assigned#

If an issue interests you but the person assigned to it seems inactive, comment on the issue or contact them to ask about progress, and offer to help or to take over. If nobody answers, ask a maintainer in the issue to reassign it.

3. Create a branch#

Contributors with write access (maintainers) can create a branch directly in the tqec repository. Everyone else can fork the tqec repository and create a branch there (see GitHub’s guide to forks). Give the branch a descriptive name. A large issue may need several PRs, each from its own branch. A git worktree gives each branch its own directory, so you can work on several at once.

4. Work in your branch#

Implement your change in that branch only. To set up a development environment, follow the developer installation.

Run the fast tests first:

uv run pytest

Run the slow (integration) tests with:

uv run pytest -m slow

Update existing tests if your change requires it, and add tests for every new class or function; see tests/ for examples. If you are new to the code base, test_compile_memory in tests/compile/compile_test.py is a good place to see the compilation pipeline end to end.

If you change the documentation, make fasthtml (run in docs/) builds it quickly. It does not execute notebook cells, it does not run the gallery examples, and it skips the user guide pages that execute code or run long simulations (quick_start, detailed_plots, collada_interop, build_computation and bgraph). Your PR is checked with the full build (make html), which runs all of them, and with a link check (make linkcheck). See Building documentation locally for both builds, and Contributing to documentation for the rules specific to documentation changes.

5. Open a pull request#

When your change is ready for review, or at least ready to be read by others, open a pull request (PR) against the main branch of tqec. Fill in the pull request template. Explain what the change does, which issue it addresses and how you tested it, and complete the “AI use” section. A maintainer may close a PR whose description is empty, is missing the template’s sections, or still contains the template’s placeholder text. A PR from an account with a private profile is closed automatically, so make your profile public before you open one. If the change is growing large, open a draft PR early so that others can look at it before it is finished.

6. Review and merge#

A PR is merged once at least one maintainer has reviewed and approved it. Iterate with the reviewers until then.

  • Contributors with write access (maintainers) can merge the PR themselves with the “Merge” button.

  • External contributors (no write access) cannot merge. Instead, add a comment such as “Ready to merge” on the PR, and a maintainer will merge it.

After the merge, delete your branch.

Inactive pull requests#

A scheduled job runs daily and manages inactive pull requests. A PR with no activity for 30 days is labelled stale with a comment. If there is still no activity 7 days after being marked stale, the PR is closed. PRs with an open review request carry the needs-review label and are never marked stale; the label is added and removed automatically. Issues are never marked stale or closed by this job.

To keep a PR open, push a commit, comment, or request a review. If your PR was closed this way, you can ask a maintainer to reopen it.

AI use#

You may use AI tools such as large language models (LLMs) to help you contribute. You are responsible for reading and understanding all code and comments you post. Maintainers review contributions with these expectations:

  • Be concise. Keep issues, comments and PR descriptions short and specific. Long AI-generated text that repeats what is already known, or does not answer the discussion, takes reviewers’ time. It may be closed or marked as off-topic without further review.

  • Submit only code that can be verified. Maintainers merge code only when they can check that it is correct, through readable changes, tests and a clear explanation. A feature or bug fix that reviewers cannot test will not be merged. In general, the more clearly verifiable evidence you present, the faster your PR will be merged.

  • Understand your contribution. Be ready to explain your changes and to answer reviewers’ questions in your own words. A PR whose author cannot answer questions about it may be closed.

Repeatedly ignoring these expectations may lead to being blocked from the repository.

If you are new to tqec, you do not need to be perfect. Mistakes are a normal part of learning, so please do not feel you have to rely on an AI tool to produce and/or explain your code. What matters is that you can read and understand what you submit.

Saying how you used AI#

Please say how much you used an AI tool to write a text you post on GitHub. The pull request and issue templates end with an “AI use” section for this, with four options: no AI tool, AI-assisted, AI-generated, and AI-translated. The difference that matters is whether you did the research and wrote the change yourself, or an AI tool did. Saying that you used AI is welcome and is never a reason to reject a contribution; it helps reviewers decide how to read it.

Automated review with Greptile#

Greptile is an AI code review bot. It reviews pull requests to tqec automatically and posts its findings as comments. tqec uses Greptile through a free trial that lasts one year and ends in July 2027.

  • It is not a substitute for human review. A PR still needs a maintainer’s approval to be merged.

  • How you use it, and whether you act on its comments, is up to you and your reviewers.

Some PRs are also reviewed by GitHub Copilot. The same applies to its comments.

Interacting with Greptile#

Mention @greptileai in a PR comment to ask for a review or a specific check, for example @greptileai are there code improvements I can make?. Reply in its comment threads to discuss a finding, and react with a thumbs up or a thumbs down to tell it which kinds of comments are useful. Read Developer essentials to make the most of it.

Configuration#

Greptile’s settings are managed in the Greptile dashboard:

  • Custom context. Greptile reads project rule files such as AGENTS.md or CLAUDE.md when the repository contains them (Greptile changelog). tqec has no such file today, so adding one changes what Greptile checks in reviews. Treat such a PR as a change to the review policy.

  • Code review. Comments from CI bots on GitHub are filtered out, Greptile is tuned to comment only on significant issues, and its review comments are collapsed by default.

To change the configuration, email kabir@u.northwestern.edu.

Getting help#

  • Ask in the issue you are working on, or open an issue with the “Asking a question” template.

  • Join the weekly online meeting, every Wednesday at 8:30am Pacific time. It is used to discuss project progress and to give educational talks, and everyone is welcome.

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
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.

Building documentation locally#

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

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:

  • Running the gallery examples (docs/gallery/*.py); their pages are built without output

  • 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 or gallery script, use the footcite role:

:footcite:`CitationKey`

When adding a gallery example, write it as a standalone Python script (.py) inside the gallery/ directory. Use standard Sphinx-Gallery docstrings at the top and # %% block comment markers to separate prose explanations and headings from executable code.

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::

Architecture overview#

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