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.
Release phases
Section titled “Release phases”| Phase | Version line | What we promise |
|---|---|---|
| Alpha | 0.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. |
| Beta | TBD | The API shape is settled. The gates are checks the maintainer runs. See Path to beta. The change policy stays in force. |
| 1.0.0 | TBD | After 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. |
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.xare safe to take. - Use hosted
^0.36.0carets on pub.dev — not legacy0.x.y-devpre-release tags. - Only the curated surfaces are supported for users. The GA
hashicorp/googlecatalog is filled interradart_google; beta-only types ship interradart_google_beta(110 resource factories).terradart_aws,terradart_azure,terradart_cloudflareandterradart_appwriteare filled at their exact provider pins (every resource and data source).
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 the public APIs ofterradart_core, the provider packages orterradart_cli. - Minor releases (
0.N.x→0.M.x): breaking changes allowed only with aMIGRATING.mdsection for the previous minor. - Curated factory additions continue (additive waves); renaming or removing curated factories still counts as breaking.
What already runs
Section titled “What already runs”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.
Path to beta
Section titled “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.dartrequires that flag on every Google resource override and every google-beta resource override.tool/wrap_lanes_test.dartrequires it on every resource override of aws, azure, cloudflare, and appwrite.terradart wrap --checkfails on a group it cannot seal, unless the override’sunsealedGroupsgives 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.dartfails whiletool/sealed_name_debt.yamlhas an entry, so anOrplaceholder cannot ship in a release.terradart lint-overridefails on any line intool/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, orIamPrincipalorAppwritePermissionwhentool/reference_targets.yamlsays so.terradart wrapfails (E406) on a staleexclude, 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 anexcludeentry names it with a reason. Callers read computed attributes through getters (deriveOutputGetters).yaml_loader_test.dartrequires that flag on every google-beta resource override.tool/wrap_lanes_test.dartrequires it on every resource override of every lane, soterradart_google,terradart_google_beta,terradart_aws,terradart_azure,terradart_cloudflare, andterradart_appwriteare 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.dartcompares every enum against Magic Modules, else Discovery, else an entry intool/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.dartrefreshes the Discovery copy, andterradart wrap --checkfails 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-nestedfails when a Google constructor input or nested helper field is stillTfArg<String>although its Magic Modulesenum_valuesor its schema description lists the values, unlesstool/enum_gap_debt.yamlrecords a reason. That file is empty, and a stale line fails the check. The check reads descriptions twice. One reader is the enum parserwrapuses. 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 intool/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 setsderiveEnums(yaml_loader_test.dart). On aws, azure, cloudflare, and appwrite,tool/wrap_lanes_test.dartrequiresderiveEnumson every resource and data-source override, andtool/data_source_enum_test.dartfails on a data-source input that is stillTfArg<String>although its description or hint file lists the values.terradart wrapfails (E405) when one of those hint files has aprovider_versionthat does not match the fixture.tool/enum_validated_values_test.dartfails 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’senumValuesgives it, andterradart wrapfails (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.dartfails a generated name over 80 characters that is more than one Terraform segment past the type it is named after, unlesstool/type_name_length_debt.yamlgives a reason.tool/type_name_stutter_test.dartfails a name that repeats words from its resource stem when the shorter name is free, unlesstool/type_name_stutter_debt.yamlgives a reason.tool/type_name_clash_test.dartfails when two provider packages export one type name. Both debt files are empty, and a stale line in either fails its test.wrapfails when atypeNamesentry names no derived enum or helper. - The migrator can express the public API.
tool/migrate_api_coverage_test.dartreads 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.yamlexcuses 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,RefToand 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.dartmigrates 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.dartfails when a lane’s fixture misses a shape its manifest declares, or a type a MIGRATING.md rename table names for that lane, andpackages/terradart_migrate/test/golden/shapes/holds the Dart each fixture migrates to.dart tool/migrate_fixture_gates.dartmigrates the checked-in trees, analyzes the generated package, synthesizes it, and runsterraform validate. A resource the command keeps in Terraform needs a reason intool/migrate_roundtrip_debt.yaml. A shape the manifest cannot derive needs amanualreason intool/migrate_manifest_debt.yaml, or amigrate:hint on the slot. Both files are empty.terradart lint-overridefails 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.dartcompiles eachdartfence 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 underlib/generated/, and eachdartfence that opens right after the///(and at most one space) of a doc comment in every workspace package exceptterradart_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 adoc-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.dartcompiles the Before and After cells of the unreleasedMIGRATING.mdsection, where a lower camel case name a cell leaves undefined is adynamicstand-in and an undefined capitalized name fails.tool/doc_renames_test.dartfails 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 aMIGRATING.mdcode 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_cliincluded). 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 underlib/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 ofMIGRATING.mdare the record and stay as written.tool/inline_fragments_test.dartfails on an inline code span, in the documents the snippet check reads and in the///doc comments of every workspace package exceptterradart_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 istrue,false,nullor 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 docount:2andname: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.dartfails 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 ajsoncfence 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.dartfails when the docs disagree with the repo on carets, catalog counts, version lines, provider pins, or the weekly bump table.tool/argument_rules_test.dartfails when a copy of the argument-writing rules drifts from Writing arguments.
Toward 1.0.0
Section titled “Toward 1.0.0”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.
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.