Skip to content
TerraDart

Status & versioning

TerraDart is alpha on the 0.24.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.24.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.24.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.24.x carets on pub.dev — not legacy 0.x.y-dev pre-release tags.
  • Only the curated terradart_google surface is supported for users; non-curated resources require a curation request.

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 467 curated resource factories + 1 data source (468 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 + five tools).

Toward 1.0.0 (does not block beta):

  • MIGRATING.md / site migration guide — Migrating mirrors the 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).