Skip to content

Status & versioning

TerraDart is alpha on the 0.36.x line today. Alpha is where TerraDart gets into people’s hands and their feedback shapes the API. The change policy below stays in force through beta and up to 1.0.0.

There are no SemVer guarantees until v1.0.0. Breaking changes land only on minor bumps. Pin with ^0.36.0, take patch releases freely, and read MIGRATING.md before every minor bump. Check pub.dev for the latest patch.

PhaseVersion lineWhat we promise
Alpha0.36.x (current)Alpha is where TerraDart gets into people’s hands and their feedback shapes the API. No breaking changes within a minor (^0.N.x). Breaking changes land only on minor bumps, each with a MIGRATING.md section. Not SemVer until 1.0.0.
BetaTBDThe API shape is settled. The gates are checks the maintainer runs. See Path to beta. The change policy stays in force.
1.0.0TBDAfter beta, two minor releases in a row ship with no breaking changes. Neither release needs a new MIGRATING.md section. Stable SemVer for terradart_core, every provider package (terradart_google, terradart_google_beta, terradart_aws, terradart_azure, terradart_cloudflare, terradart_appwrite, terradart_time), and terradart_cli. terradart_codegen, terradart_migrate, and terradart_hcl stay outside the promise.
  • 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.36.0 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 (110 resource factories). terradart_aws, terradart_azure, terradart_cloudflare and terradart_appwrite are filled at their exact provider pins (every resource and data source).
  • Patch releases (0.N.x → 0.N.y): no intentional breaking changes to the public APIs of terradart_core, the provider packages or terradart_cli.
  • 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.

Every maintainer-side gate already runs on each pull request. That set includes docs consistency, every example synthesized and checked with terraform validate, and example coverage of every catalog entry (or a reasoned entry in the example ledger). Beta uses the checklist under Path to beta.

Beta means the API shape is settled. The gates are checks the maintainer runs. Alpha is where TerraDart gets into people’s hands and their feedback shapes the API. Beta waits on the checklist below.

These are the beta gates. The boxes stay open until each one is met.

  • Sealed groups have concept names. Every exclusive group is one sealed argument, named for the concept (the override sets deriveExactlyOne). yaml_loader_test.dart requires that flag on every Google resource override and every google-beta resource override. tool/wrap_lanes_test.dart requires it on every resource override of aws, azure, cloudflare, and appwrite. terradart wrap --check fails on a group it cannot seal, unless the override’s unsealedGroups gives the reason, and on a derived helper no constructor reaches. A hand-written sealed argument counts when its variants cover the group. dart tool/release_ledger_check.dart fails while tool/sealed_name_debt.yaml has an entry, so an Or placeholder cannot ship in a release. terradart lint-override fails on any line in tool/exactly_one_lint_debt.yaml, so the file stays empty.
  • References and outputs are typed. A string input that names another resource is a RefTo, or IamPrincipal or AppwritePermission when tool/reference_targets.yaml says so. terradart wrap fails (E406) on a stale exclude, an attribute the target does not export, or an input two rules claim. It also fails (E406) on a matched input that stays a string, unless an exclude entry names it with a reason. Callers read computed attributes through getters (deriveOutputGetters). yaml_loader_test.dart requires that flag on every google-beta resource override. tool/wrap_lanes_test.dart requires it on every resource override of every lane, so terradart_google, terradart_google_beta, terradart_aws, terradart_azure, terradart_cloudflare, and terradart_appwrite are covered.
  • A fixed set of values is an enum. Every fixed value set that a checked-in machine source has is an enum. The machine sources are the Magic Modules enum_values, the provider validators (the hint files of aws, azure, cloudflare and appwrite), and a checked-in copy of the Google API Discovery enums. Each Discovery document in that copy records its API, version, revision and source URL. On every lane, Google included, a check compares the emitted values exactly against those sources. A value set that only prose gives is typed on a best-effort basis and needs a reasoned entry. On google and google-beta, tool/google_enum_sources_test.dart compares every enum against Magic Modules, else Discovery, else an entry in tool/enum_prose_sources.yaml. That entry lists the exact values and says why no machine source covers them (no Discovery document, no Discovery enum at the path, or a reviewed note on why the provider accepts a value the source lacks). The test also fails on an input that stays a plain string although Magic Modules or Discovery has its values. tool/fetch_discovery_enums.dart refreshes the Discovery copy, and terradart wrap --check fails when the copy no longer matches the provider pin, the Magic Modules ref or the wrapped types. dart tool/check_google_enum_gaps.dart --strict-nested fails when a Google constructor input or nested helper field is still TfArg<String> although its Magic Modules enum_values or its schema description lists the values, unless tool/enum_gap_debt.yaml records a reason. That file is empty, and a stale line fails the check. The check reads descriptions twice. One reader is the enum parser wrap uses. The other is a looser reader of its own, which takes every quoted, upper-case or call-shaped token (deny(403)) after a value-set cue (Possible values, Allowed, Supported, Valid, One of, either). So a wording the parser skips still fails the check. A cue that introduces no value set (sibling inputs, resource-name formats, examples of an open set) is listed with its reason in tool/enum_gap_cue_prose.yaml. A line there can excuse only a hit of the looser reader, and a stale line fails the check. Every google-beta resource override sets deriveEnums (yaml_loader_test.dart). On aws, azure, cloudflare, and appwrite, tool/wrap_lanes_test.dart requires deriveEnums on every resource and data-source override, and tool/data_source_enum_test.dart fails on a data-source input that is still TfArg<String> although its description or hint file lists the values. terradart wrap fails (E405) when one of those hint files has a provider_version that does not match the fixture. tool/enum_validated_values_test.dart fails when a generated enum on one of those lanes emits a value outside the hint file’s set for its input, or when an enum’s values look like Go constant names. Where the upstream set is wrong or sits in prose, the override’s enumValues gives it, and terradart wrap fails (E406) on an entry that names no string attribute or repeats the derived set.
  • Type names stay short and unique. tool/type_name_length_test.dart fails a generated name over 80 characters that is more than one Terraform segment past the type it is named after, unless tool/type_name_length_debt.yaml gives a reason. tool/type_name_stutter_test.dart fails a name that repeats words from its resource stem when the shorter name is free, unless tool/type_name_stutter_debt.yaml gives a reason. tool/type_name_clash_test.dart fails when two provider packages export one type name. Both debt files are empty, and a stale line in either fails its test. wrap fails when a typeNames entry names no derived enum or helper.
  • The migrator can express the public API. tool/migrate_api_coverage_test.dart reads every provider package’s wrappers with the analyzer and fails on a public factory its migration manifest has no entry for, with the same Terraform type and kind. tool/migrate_unmanifested_factories.yaml excuses an omission only when it names another package whose manifest builds that class with the same inputs and getters. The test also fails on any constructor input or output getter, inherited ones included, that the manifest cannot build with the same shape: a scalar, an untyped block, an enum, EnumList, sealed choice and its Terraform keys, RefTo and the attribute it emits, IAM principal or helper block. For a sealed choice it checks where the value is encoded and that each variant’s shorthand is a factory constructor that builds that variant. dart tool/migrate_roundtrip_gates.dart migrates every quickstart and a shape fixture per lane (google, google-beta, aws, azure, cloudflare, appwrite, time), analyzes the Stacks, synthesizes them again and fails on any difference from the original JSON. tool/migrate_shape_fixtures_test.dart fails when a lane’s fixture misses a shape its manifest declares, or a type a MIGRATING.md rename table names for that lane, and packages/terradart_migrate/test/golden/shapes/ holds the Dart each fixture migrates to. dart tool/migrate_fixture_gates.dart migrates the checked-in trees, analyzes the generated package, synthesizes it, and runs terraform validate. A resource the command keeps in Terraform needs a reason in tool/migrate_roundtrip_debt.yaml. A shape the manifest cannot derive needs a manual reason in tool/migrate_manifest_debt.yaml, or a migrate: hint on the slot. Both files are empty. terradart lint-override fails a stale line in that file, and it fails an underivable shape that has no reason.
  • The docs match the API. Each check below catches the forms it names and no others, so a crafted input outside them can still pass. tool/doc_snippets_test.dart compiles each dart fence outside a block quote in the README, the agent skill, the website docs, and the package, cookbook and example READMEs, with the readers a recipe or example checks in under lib/generated/, and each dart fence that opens right after the /// (and at most one space) of a doc comment in every workspace package except terradart_codegen, each in a sandbox that depends on its own package. A blockquoted fence and a doc-comment fence indented further are not read. A fence must declare every value it reads, so every argument has the type the real API gives it. A fence the check reads leaves it only behind a doc-snippets: skip: marker with a reason, and the test fails on a skipped fence that imports no package outside the workspace. tool/migrating_cells_test.dart compiles the Before and After cells of the unreleased MIGRATING.md section, where a lower camel case name a cell leaves undefined is a dynamic stand-in and an undefined capitalized name fails. tool/doc_renames_test.dart fails when a guide or a doc comment names a removed or an internal symbol. A removed symbol is one the public API no longer declares and that either a MIGRATING.md code span names (a type, a type and member, or a whole lower camel case span; a span wrapped across lines included) or the last release exported (a type; a member, one inherited from a supertype or read through a typedef included; or a top-level name; terradart_cli included). The public API, now and at the last release, is what each package’s entrypoints export, read from the analyzer’s export namespace; a declaration under lib/src/ that no entrypoint exports is internal. A name counts in prose, a code span (one split across lines included), a fence or a dartdoc reference in brackets, with or without a lowercase prefix such as an import prefix. A one-word type name and a name with no capital letter count only in code, a span of plain words names nothing, and a dartdoc [Type] or [Type.member] reference (a capitalized type, a lowercase member) must resolve; a reference that opens lowercase is not checked. The check merges the members of same-named declarations and counts an unnamed extension in an entrypoint as public. The doc comment of an exported declaration may not name an internal one; other doc comments may name their own package’s. Its allow list (tool/doc_renames_allow.yaml) is reviewed, and a stale entry fails. The Before cells and the released sections of MIGRATING.md are the record and stay as written. tool/inline_fragments_test.dart fails on an inline code span, in the documents the snippet check reads and in the /// doc comments of every workspace package except terradart_codegen, that spells an argument (a lowercase name, a colon and a value), on its own or inside a call. Two forms pass. One is a snake_case key with a plain scalar, which is Terraform, YAML or JSON. The other is a span that opens on a name and a colon with no space, unless its value is true, false, null or a lowercase dotted member chain, contains a parenthesis, or opens with a quote, r' (a single-quoted raw string only; r" is not caught), a square bracket, a dot, const, or a capitalized name followed by a parenthesis, a dot or an angle bracket. So a URI, principal, IAM action or port passes, and so do count:2 and name:orders. Spans are read across the lines of a paragraph, inside block quotes and behind longer backtick runs; a paragraph ends at a blank line, a fence, an ATX heading, a row of a GFM table, a bullet item, or an ordered item numbered 1 or inside a list. A line of three backticks opens a fence at any indentation, where CommonMark reads four spaces as indented code. tool/example_synth_gates.dart fails when a JSON fence of an example README is not what that example synthesizes: a fence of backticks or tildes whose info string’s first word is json in any case (so a jsonc fence is not read), at the top level, in a block quote or in a list item, with LF or CRLF line endings. dart tool/check_docs_consistency.dart fails when the docs disagree with the repo on carets, catalog counts, version lines, provider pins, or the weekly bump table. tool/argument_rules_test.dart fails when a copy of the argument-writing rules drifts from Writing arguments.

1.0.0 comes after beta. Two minor releases in a row ship with no breaking changes. Neither release needs a new MIGRATING.md section. A later minor that adds a MIGRATING.md section starts that count again. A schema bump that removes a provider type is one of those minors. Reports of real usage inform the maintainer. The 1.0 label waits on beta, then on those two releases.

Stable SemVer then covers the packages in the table above.

Upgrading covers the current minor’s breaking changes. MIGRATING.md on GitHub remains the record for older releases. Each minor’s upgrading guide still covers that minor and the one before it. That rule is about the guide. The 1.0 rule is the two releases above.

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

Use the bug or question template on GitHub.