Skip to content

docs(readme): split supported migration paths by v4 source version - #332

Merged
vaishakdinesh merged 1 commit into
mainfrom
docs/v4-source-version-support-matrix
Oct 13, 2026
Merged

vaishakdinesh merged 1 commit into
mainfrom
docs/v4-source-version-support-matrix

Conversation

@vaishakdinesh

@vaishakdinesh vaishakdinesh commented Oct 13, 2026 •

Copy link
Copy Markdown
Member

What changed

cloudflare_ruleset's state-upgrade bug only fires when v4 state contains asset_name (added v4.52.8) or content_converter (added v4.52.9) — fields the v5 source schema doesn't fully support parsing until v5.22.0+ (and even then only asset_name; content_converter remains unhandled through v5.23.0). v4.52.5–v4.52.7 never write either field, so ruleset migrates cleanly from that range on every target version.

Confirmed empirically: live-tested a direct v4.52.5 → v5.19.1 migration of cloudflare_ruleset and cloudflare_api_token against real Cloudflare infrastructure. ruleset applied with zero references to either field in plan/apply/error output. The only failure was the already-documented api_token policies-swap bug, unrelated to v4 source version.

  • Split Supported Migration Paths into two source-version bands (v4.52.5–v4.52.7 vs v4.52.8–v4.52.9) with per-version known-issue counts
  • Added a dedicated "Migrating from v4.52.5 – v4.52.7 specifically" section with a full resource-by-resource breakdown per target version, and a clear recommendation (target v5.22.0 — only d1_database remains, which tf-migrate already works around)
  • Dropped v5.19.0 from both tables (out of practical scope going forward) and renumbered the now-orphaned footnote
  • Rewrote footnote 5 to state the mechanism precisely (which fields, which v4/v5 versions) and point to the new section instead of hedging with "likely unaffected"

cloudflare_ruleset's state-upgrade bug only fires when v4 state contains
asset_name (added v4.52.8) or content_converter (added v4.52.9) — fields
the v5 source schema doesn't fully support parsing until v5.22.0+ (and
even then only asset_name; content_converter remains unhandled through
v5.23.0). v4.52.5-v4.52.7 never write either field, so ruleset migrates
cleanly from that range on every target version, confirmed via a live
v4.52.5 -> v5.19.1 test against real Cloudflare infrastructure.

- Split "Supported Migration Paths" into two source-version bands
  (v4.52.5-v4.52.7 vs v4.52.8-v4.52.9) with per-version known-issue counts
- Add a dedicated "Migrating from v4.52.5 - v4.52.7 specifically" section
  with a full resource-by-resource breakdown per target version
- Trim the v5.19.0 column/rows from both tables (out of practical scope)
  and renumber the orphaned footnote
- Rewrite footnote 5 to state the mechanism precisely and point to the
  new section instead of hedging with "likely unaffected"
@vaishakdinesh
vaishakdinesh requested a review from a team as a code owner October 13, 2026 16:05
@vaishakdinesh
vaishakdinesh merged commit dda06fa into main Oct 13, 2026
11 checks passed
@vaishakdinesh
vaishakdinesh deleted the docs/v4-source-version-support-matrix branch October 13, 2026 16:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants