How TerraDart is built and maintained

If you are deciding whether to depend on TerraDart, two questions matter more than any feature list: why should I trust hundreds of generated factory classes? and why should I expect this project to keep up with Google Cloud? This page answers both with mechanisms you can inspect in the repository — every claim below names something that actually runs, not an aspiration.

The generation pipeline

Curated factories are not written by hand. They are generated by a maintainer CLI (terradart wrap) from two pinned inputs: the Terraform provider schema for hashicorp/google, and Magic Modules metadata — the upstream YAML Google uses to generate the provider itself, synced per-resource with provenance recorded for every file.

Generation is byte-deterministic: CI re-runs the generator against the pinned inputs on every pull request and fails if a single generated file differs from what is committed. There is no “mostly generated, occasionally hand-patched” gray zone — generated files carry a do-not-edit banner, repo tooling blocks direct edits, and the parser that extracts enum values from schema descriptions is the same code the coverage checker runs, so the generator and its auditor cannot drift apart.

The curation philosophy

The rule is simple: facts are derived, judgment is declared, and both are auditable.

• Anything the schema or Magic Modules can state — parameters, enum values, output getters, nested block shapes, documentation — is derived, so it moves automatically when upstream moves.
• Human decisions — which resources to curate, how to model an exactly-one-of block as a sealed class hierarchy, which surfaces to freeze deliberately — live in thin, reviewable override files.
• Every escape hatch is a fail-closed ledger: skipped examples, frozen surfaces, cost classifications, and coverage debts are recorded lines with reasons, and CI fails when an entry goes stale. Forgetting is impossible to do silently.

This is also why the API is opinionated: IAM adjuncts default to additive *_iam_member variants, and mutually-exclusive nested blocks are enforced at compile time with sealed classes instead of documented conventions.

The verification harness

Type-checking generated code proves it compiles, not that it works. Verification is layered from cheap to expensive:

The last layer is the one most projects skip: apply-eligible examples are actually applied and destroyed in a real GCP project — automatically on any pull request that touches an example, and as a monthly full sweep. When you upgrade TerraDart and your synthesized JSON is unchanged, that is not luck; it is the property this harness exists to protect.

Sustainability

TerraDart is a single-maintainer project, and you should weigh that honestly. Here is what makes it a smaller risk than the label suggests: the routine work does not depend on the maintainer being present.

• The update loop runs unattended. Provider schema updates arrive as automatic weekly pull requests; a scheduled agent triages each one; merging is guarded by an independent mechanical gate (an allow-list of touchable paths plus the full CI battery), not by anyone’s availability. Routine Google Cloud drift is absorbed on a cadence.
• The repository is deliberately maintainable by others — human or AI. A single agent guide is the source of truth for how to work on the codebase; the ledgers make every standing decision explicit; determinism makes every regeneration verifiable. A successor does not need tribal knowledge, and most routine maintenance is already performed by agents under the gates above.
• Lock-in is shallow by design. The output is standard Terraform JSON. If the project stopped tomorrow, your existing configurations would keep working with plain terraform apply — and migrating away is a file-format decision, not a re-architecture.

What is not promised: there is no SLA. Issue triage and reviews are best-effort, and security response targets are documented in SECURITY.md. The status page states the current release phase and change policy in the same spirit.

Read more

• Architecture — how your stacks work at runtime: synth(), providers, and the AppExport seam.
• Coverage — every curated factory and the examples that exercise it.
• Contributing or pointing an agent at the repo? Start with AGENTS.md.