This guide covers strategies for organizing PDK repositories and managing tapeouts over time. Choosing the right structure early prevents maintenance headaches as your team scales across multiple tapeouts.

The problem¶

A PDK is a living codebase: it evolves with each tapeout, but completed tapeouts must stay frozen so they remain reproducible. Balancing evolution with reproducibility is the central challenge.

Repository structures¶

There are three common approaches, each with different tradeoffs.

1. Mutable PDK in monorepo¶

A single repository where the PDK and each tapeout live as sibling directories, with the PDK as the shared, evolving source of truth.

pdk-repo/
    pdk/                # Plan of record (evolves)
    tapeout1/
        tapeout1_files/
    tapeout2/
        tapeout2_files/

Use branches or tags (_v1, _v2, _v3) to snapshot PDK state for each tapeout.

Pros:

• Single location for all files — easy to tell people where to look.

Cons:

• The repo becomes a monolith that is hard to maintain.
• Completed tapeouts can break when the PDK evolves.
• Many open PRs accumulate, making the repo hard to navigate and archive.

2. New PDK per tapeout in monorepo¶

Similar to the complex monorepo, but each tapeout directory includes its own frozen copy of the PDK.

pdk-repo/
    pdk/                    # Plan of record (evolves)
    tapeout1/
        pdk/                # Frozen after tapeout1 is done
        tapeout1_files/
    tapeout2/
        pdk/                # May diverge from tapeout1's copy
        tapeout2_files/

Pros:

• Single location for all files.
• Each tapeout has its own PDK snapshot.

Cons:

• Tends to get messy over time (accumulated files, many open PRs).
• Tapeouts can still break if shared dependencies change.
• Hard to archive completed tapeouts without affecting the rest of the repo.

3. Multi-repo (recommended)¶

Each tapeout lives in its own repository with an independent copy of the PDK. A shared CI/CD repo provides common tooling.

pdk-centralized-cicd/       # Shared tools for all repos
repo1: pdk/                 # Plan of record (evolves independently)
repo2: tapeout1/
    pdk/                    # Frozen after tapeout1 is done
    tapeout1_files/
repo3: tapeout2/
    pdk/                    # Frozen after tapeout2 is done
    tapeout2_files/

Pros:

• Completed tapeout repos can be archived and will always work.
• Improvements from any tapeout can be selectively copied back to the main PDK repo.
• Each repo stays focused and manageable.

Cons:

• Files are spread across multiple repos — use README files with cross-links to connect them.
• Requires maintenance of the centralized CI/CD repo.

Recommended workflow¶

1. Start from the PDK repo. Develop and iterate on the plan-of-record PDK.
2. Copy plan of record PDK for each tapeout. When a tapeout begins, create a new repo (e.g., tapeout-<name>) with a copy of the current PDK.
3. Freeze on completion. After tapeout is done, archive the repo. The frozen PDK and locked dependencies ensure reproducibility. You can still use tags and releases to add comments and metadata. (like sent to foundry, re-worked metallization, etc.)
4. Backport improvements. Copy relevant improvements from tapeout repos back into the main PDK repo for future tapeouts.
5. Use XOR regression tests. Each tapeout repo should include regression tests to catch unintended layout changes.

Naming conventions¶

Use a consistent naming scheme for tapeout repos:

tapeout-<name>          # e.g., tapeout-alpha, tapeout-2026q1

Link tapeout repos from the main PDK repo's README so the full history is easy to navigate.

Extra files to include¶

repo: tapeout1/
    pdk/                    # Frozen after tapeout1 is done
    tapeout1_files/
    docs/
    tests/ # regression tests, with XOR comparisons to catch unintended layout changes
    pyproject.toml # with pinned dependencies
    uv.lock # with pinned dependencies