Skip to content
TerraDart

Status & versioning

TerraDart is alpha on the 0.28.x line today. Alpha means the maintainer-side quality gates are all done (see Alpha gates) and the change policy below is in force; what still separates alpha from beta is external validation — see Path to beta.

There are no SemVer guarantees until v1.0.0, but breaking changes land only on minor bumps: pin with ^0.28.x, take patch releases freely, and read MIGRATING.md before every minor bump. Check pub.dev for the latest patch.

Release phases

Section titled “Release phases”
PhaseVersion lineWhat we promise
Alpha0.28.x (current)Maintainer-side gates are done (docs, CI, real-apply coverage). No breaking changes within a minor (^0.N.x); breaking changes only on minor bumps, always documented in MIGRATING.md. Not SemVer until 1.0.0.
BetaTBD (needs external validation)The same change policy, proven against real external usage — see Path to beta.
1.0.0TBDStable SemVer for terradart_core, terradart_google, and terradart_codegen.

What to expect today (alpha)

Section titled “What to expect today (alpha)”
  • Breaking changes to the public Dart API or the emitted Terraform JSON land only on minor bumps, each with a MIGRATING.md section; patch releases within ^0.N.x are safe to take.
  • Use hosted ^0.28.x carets on pub.dev — not legacy 0.x.y-dev pre-release tags.
  • Only the curated surfaces are supported for users. The GA hashicorp/google catalog is filled in terradart_google; beta-only types ship in terradart_google_beta (128 resource factories). terradart_appwrite is filled at 2.0.0-beta.1 (38 resource factories + 24 data sources). terradart_cloudflare is filled at 5.23.0 (257 resource factories + 446 data sources).

Change policy (from alpha onward)

Section titled “Change policy (from alpha onward)”
  • Patch releases (0.N.x → 0.N.y): no intentional breaking changes to terradart_core / terradart_google public APIs.
  • Minor releases (0.N.x → 0.M.x): breaking changes allowed only with a MIGRATING.md section for the previous minor.
  • Curated factory additions continue (additive waves); renaming or removing curated factories still counts as breaking.

Alpha gates (complete)

Section titled “Alpha gates (complete)”

Alpha required every item below; all are done. (This list was the former “beta readiness checklist” — beta is now gated on external validation instead.)

  • Getting Started on terradart.dev matches the README quickstart; no “Coming soon” placeholders on Status or Getting Started.
  • tool/check_docs_consistency runs in CI and passes (workspace + examples caret minor, catalog count, key meta docs). Workflow: .github/workflows/docs-consistency.yml.
  • tool/smoke_quickstart.sh runs in CI and passes (pubsub_quickstart: pub get → synth → analyze including export consumer stub).
  • Examples matrix on main stays green (per-example synth + terraform validate on tf-out/).
  • Boundary demo: pubsub_quickstart documents addExport / generated .app.dart and includes a subscriber stub that dart analyze accepts.
  • Meta docs aligned with the current minor: CONTRIBUTING, SECURITY, issue templates, package READMEs, and root README agree on alpha/beta wording, ^0.N.x pins, and 1337 curated resource factories + 461 data sources (1798 catalog entries).
  • Full example coverage: tool/example_debt.yaml is empty — all catalog entries appear in at least one quickstart synth (check_docs_consistency.dart).
  • Change policy published on this page (see Change policy) and in force from alpha.

Path to beta

Section titled “Path to beta”

Beta is the alpha change policy proven against real external usage. We will label the project beta when:

  • External quickstart: someone outside the core team completes the README path once; feedback captured in an issue or discussion.
  • Real apply dogfood via the cookbook: at least one non-trivial recipe documents a successful terraform apply.
  • terradart-mcp: Agent install verified on a clean machine (Homebrew or release binary + six tools).
  • terradart-migrate: Migrating from HCL verified on a clean machine (Homebrew or release binary), with one real Terraform tree that migrates and plans with No changes.

Toward 1.0.0 (does not block beta):

  • MIGRATING.md / site migration guide — Migrating mirrors the 0.27.0 → 0.28.0 and 0.12.9 → 0.12.10 breaking changes; MIGRATING.md on GitHub remains canonical for older releases. Two-minor depth across minors remains a quality bar for current and future minor releases.
  • 1.0.0 criteria drafted (what “stable” means for curated names and terradart_core API).

What alpha does not mean

Section titled “What alpha does not mean”
  • Not a freeze on new curated factories.
  • Not constructs / composite frameworks.
  • Not SemVer until 1.0.0.
  • Not on-demand generation of arbitrary google_* bindings outside the curated surface.

Reporting issues

Section titled “Reporting issues”

Use the bug or question template on GitHub.

Maintainer notes

Section titled “Maintainer notes”

Maintainer session notes stay in the gitignored repo-root docs/ tree locally (not published).