Contributing#

We welcome contributions of all sizes—bug fixes, documentation, new components, and improvements to existing layouts or models. Please keep pull requests focused, documented, and easy to review.

How to contribute#

  • Discuss substantial changes in an issue or draft PR before investing significant effort.

  • Keep changeset size reasonable; split large efforts into smaller, reviewable chunks.

  • Add or update tests and documentation alongside code changes.

Installation for Contributors#

This project uses uv for Python package management and just as a command runner.

Clone the repository and install the development dependencies:

git clone https://github.com/gdsfactory/quantum-rf-pdk.git
cd quantum-rf-pdk
just install

Note

Git LFS must be installed to run all tests locally. Some test data files (e.g., CSV files in tests/models/data/) are tracked with Git LFS and will not be properly downloaded without it.

KLayout Technology Installation#

For contributors, you can install the technology files directly from the repository:

just install-tech

Note

After installation, restart KLayout to ensure the new technology appears.

Development workflow#

Check out the commands for testing and building documentation with:

just --list

  • Run the full test suite: just test

  • Run layout regression tests: just test-gds (or just test-gds-fail-fast while iterating)

  • Run formatting/linting hooks: just run-pre

  • Build docs (optional but encouraged when docs change): just docs

AI usage policy#

We encourage using AI tools to accelerate your workflow—for example, prototyping components and layouts, generating model visualizations, writing tests, or drafting documentation. However, do not submit “AI slop.” You are fully responsible for the quality of your contributions. Any AI-generated code, layouts, or text must be reviewed, functionally tested, and completely human-maintainable.

Justfile Commands#

The repository includes a justfile with convenient commands for common development tasks.

Available Commands#

To see the list of available commands at any time, run:

just --list

Available recipes:
    default                       # List available commands

    [all]
    all                           # Run all tests, pre-commit hooks, build wheel and documentation in parallel

    [build]
    build                         # Build the Python package (install build tool and create dist)
    show component_name=""        # Generate and show a PDK component by name (opens interactive chooser by default), saving its GDS to build/

    [docs]
    docs                          # Build the HTML documentation
    docs-latex                    # Setup LaTeX for PDF documentation
    docs-pdf                      # Build PDF documentation (requires a TeXLive installation)

    [lint]
    install-pre                   # Install pre-commit hooks to run on `git commit`
    run-pre                       # Run all pre-commit hooks on all files
    update-pre                    # Update pre-commit hooks to the latest revisions

    [setup]
    clean                         # Clean up all build, test, coverage and Python artifacts
    install extras="--all-extras" # Install the package and all development dependencies
    install-tech                  # Install KLayout technology files for the PDK

    [test]
    get-gfp-versions versions     # Filter a JSON array of Python versions to only those supported by the latest version of gdsfactoryplus on PyPI
    test *args                    # Run the full test suite in parallel using pytest
    test-gds                      # Run GDS regressions tests (tests/test_pdk.py)
    test-gds-fail-fast            # Run GDS regressions tests (tests/test_pdk.py) and stop at first failure
    test-gds-force                # Run GDS regressions tests (tests/test_pdk.py) and regenerate
    test-gfp                      # Run GDSFactory+ tests
    test-hfss *args               # Run HFSS simulation tests (requires HFSS to be installed)
    test-models                   # Run model regression tests (tests/test_models_regression.py)
    test-models-force             # Regenerate model regression reference files
    test-ports                    # Run optical port position tests (tests/test_pdk.py::test_optical_port_positions)

Usage#

To run any of these commands, use:

just <command>

Makefile Compatibility#

A Makefile is provided as a thin compatibility layer for the gdsfactory PDK CI workflows. just remains the primary task runner for day-to-day development; the Makefile exists so that make install and make test work out-of-the-box in CI environments that expect them.

make docs      # equivalent to: just docs
make build     # equivalent to: just build
make run-pre   # equivalent to: just run-pre

Code of Conduct#

We follow the gdsfactory Code of Conduct.