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

To adapt QPDK to your own fabrication process rather than contribute to it, see
[Customizing QPDK for Your Process](https://gdsfactory.github.io/quantum-rf-pdk/customizing.html.md).

## Installation for Contributors

This project uses [uv](https://github.com/astral-sh/uv) for Python package management and
[just](https://github.com/casey/just) as a command runner.

Clone the repository and install the development dependencies:

#### IMPORTANT
[Git LFS](https://git-lfs.github.com/) must be installed **before** cloning. This repository uses Git LFS to track
binary and large data files (e.g., CSV files in `tests/models/data/`). Without Git LFS, the clone will fail or those
files will not be downloaded correctly.

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

### KLayout Technology Installation

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

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

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

```bash
just --list
```

```text
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]
    build-doc-figures             # Build SVG figures from docs/figures/*.typ
    docs                          # Build the HTML documentation
    docs-pdf                      # Build PDF documentation (typsphinx compiles it with the bundled Typst compiler)
    docs-typst                    # Generate Typst sources for the PDF documentation

    [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-data                  # Download Git LFS data (FEM datasets and model test references)
    install-tech                  # Install KLayout technology files for the PDK

    [test]
    fetch-gfp $version="latest"   # Writes build/gfp-vsix/env.sh exporting GFP_BIN for `just test-gfp` to source.
    test *args                    # Uses positional arguments so quoted args survive, e.g. `just test -k "some name"`
    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 *args                # share one gfp serve process and the repo's build/ dir) on a single worker.
    test-hfss *args               # Run HFSS simulation tests (requires HFSS to be installed)
    test-models                   # Run model regression tests (tests/models/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)
    test-vacask *args             # Run VACASK simulation tests (requires VACASK, see qpdk/simulation/vacask.py)
```

### Usage

To run any of these commands, use:

```bash
just <command>
```

## Makefile Compatibility

A `Makefile` is provided as a thin compatibility layer for the
[gdsfactory PDK CI workflows](https://github.com/doplaydo/pdk-ci-workflow-public). **`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.

```bash
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](https://github.com/gdsfactory/gdsfactory)
[Code of Conduct](https://gdsfactory.github.io/gdsfactory/code_of_conduct/).