docs: add a v1 to v2 migration guide - #1884
Open
james00012 wants to merge 6 commits into
Open
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughAdded Terratest v1-to-v2 migration documentation. The changes cover behavior changes, import mappings, rewrite steps, module version guidance, documentation navigation, and wording updates. ChangesV2 migration documentation
Estimated code review effort: 2 (Simple) | ~15 minutes Mergeability Score: ⚪ Minimal · up to This PR adds migration documentation and reorganizes documentation numbering without changing product behavior; no actionable merge-blocking risk remains beyond normal checks and review. Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
james00012
marked this pull request as ready for review
August 12, 2026 03:59
Brian is dogfooding the v2 beta and the only guidance available was the beta.1 release notes plus docs/v2-import-map.md, which is a design artifact with an accounting section and a decision log rather than user docs. Adds docs/_docs/04_migrating-to-v2/, mirroring the migrating-to-v1 collection so it lands at /docs/migrating-to-v2/overview/: - overview: what changed, the order to do it in, removed packages - rewriting-imports: bulk sed for the three transformations, the two places a blind replace gets it wrong, symbol relocations, go.mod - import-map: the full v1 to v2 path table - behaviour-changes: the two k8s changes the compiler will not catch Also links forward from the v1 overview, and renumbers the community collection to 05 so ordering stays contiguous. Permalinks come from front matter, so no URLs change.
Use 'behavior' not 'behaviour', which is what the rest of docs/ uses, and rename the page accordingly. Wrap prose at 75 columns and close with a PR pointer, both matching the migrating-to-v1 collection.
james00012
force-pushed
the
docs/v2-migration-guide
branch
from
August 12, 2026 04:02
bcc2d20 to
0da1ab4
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/_docs/04_migrating-to-v2/overview.md`:
- Around line 44-46: Remove formatting from the public utility package list in
docs/_docs/04_migrating-to-v2/overview.md:44-46, and remove formatting from the
rewrite expression in docs/_docs/04_migrating-to-v2/rewriting-imports.md:22-29.
Keep the remaining public utility mappings unchanged.
In `@docs/_docs/04_migrating-to-v2/rewriting-imports.md`:
- Line 109: Update the unlabeled code fence in the migrating-to-v2 imports
documentation to use the go language tag on its opening fence, leaving the
fenced content unchanged.
- Around line 52-56: Update the migration instructions after “Then let the
compiler find the rest” to use the project’s test compilation command instead of
only “go mod tidy && go build ./...”, ensuring _test.go files and their imports
are compiled during migration.
- Around line 26-29: Update the sed commands in the import-rewriting
documentation to use POSIX ERE syntax: replace escaped alternation with plain |
under -E, and replace non-portable \b boundaries with explicit portable boundary
patterns. Ensure all three commands reliably rewrite the intended imports and
package identifiers on BSD/macOS sed.
In `@docs/v2-import-map.md`:
- Line 85: Update the “Behavior changes during the v2 beta” heading so the
legacy fragment `#behaviour-changes-during-the-v2-beta` remains valid, either by
restoring the original spelling or adding an explicit alias while preserving the
current heading.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d771a18f-75e8-4c60-a24a-e85438af232b
📒 Files selected for processing (9)
docs/_docs/03_migrating-to-v1/overview.mddocs/_docs/04_migrating-to-v2/behavior-changes.mddocs/_docs/04_migrating-to-v2/import-map.mddocs/_docs/04_migrating-to-v2/overview.mddocs/_docs/04_migrating-to-v2/rewriting-imports.mddocs/_docs/05_community/contributing.mddocs/_docs/05_community/license.mddocs/_docs/05_community/support.mddocs/v2-import-map.md
The sed commands did not work on the platform they were written for. BSD sed has no \b, so the three identifier rewrites silently did nothing on macOS, leaving every call site undefined. Use an explicit boundary class and # as the delimiter, and drop the false claim that the blocks are order-dependent. Add the alias-stripping expression, without which test_structure "..." keeps the old alias bound to the renamed package, and add gofmt. Add the largest missing step: v2 deletes everything v1 deprecated, not just the non-Context wrappers. Point at staticcheck SA1019 as the way to find it. Correct: formatting was never a v1 package and is now public at core/v2/formatting; GetServiceEndpoint has no non-Context form; 22 AWS service clients, not 23; ErrRestConfigNotSerializable is wrapped so it needs errors.Is; NodePublicIPLookup is only consulted for aws provider IDs. Verify with go test -run '^$' rather than go build, since go build does not compile _test.go and that is where a Terratest suite lives. Retitle to 'v2 overview' so it stops colliding with the v1 page on the docs index, add the missing version and go get guidance, note the v2 exception on the v1 version-pinning page, and refresh the stale category list in docs/README.md.
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/_docs/04_migrating-to-v2/overview.md`:
- Around line 23-27: Update the “Should you migrate yet” section to state that
v1 receives security fixes only, matching the support policy wording in
README.md, while preserving the surrounding migration guidance.
- Around line 128-129: Update the introductory sentence near “Six packages and
two binaries are not carried forward” to replace “Most” with an accurate
statement that only three packages have standard-library replacements, such as
“Three have a standard-library replacement.”
- Around line 123-124: Update the migration overview’s “Steps 1 to 4” guidance
so a successful build only resolves the compile-error steps, not the entire
migration. Explicitly require completing the manual Kubernetes behavior review
in Step 5 before marking the migration complete.
In `@docs/_docs/04_migrating-to-v2/rewriting-imports.md`:
- Around line 35-43: Update the final cleanup expression in the import-rewriting
command to match any whitespace indentation, including spaces, instead of only
tabs. Preserve the existing alias removal for http_helper, dns_helper, and
test_structure so space-indented imports are rewritten to the correct package
names.
In `@docs/README.md`:
- Line 189: Correct the wording in the order description by changing “it is use”
to “it is used,” preserving the existing ordering guidance and examples.
- Line 92: Update the documentation metadata example and description in
docs/README.md to use the singular category field instead of categories, while
preserving the listed category values and navigation guidance.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d4dcd9e5-746a-4baa-b8f1-77aeb60abf73
📒 Files selected for processing (7)
README.mddocs/README.mddocs/_docs/01_getting-started/version-pinning.mddocs/_docs/04_migrating-to-v2/behavior-changes.mddocs/_docs/04_migrating-to-v2/import-map.mddocs/_docs/04_migrating-to-v2/overview.mddocs/_docs/04_migrating-to-v2/rewriting-imports.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/_docs/04_migrating-to-v2/import-map.md
- docs/_docs/04_migrating-to-v2/behavior-changes.md
Match README's v1 policy wording (security fixes only, not 'gets fixes'). Stop implying a green build means the migration is done, since the k8s behavior changes compile either way. Three of the six removed packages have a standard library replacement, not most. Strip aliases from space-indented import blocks too, not just tab-indented ones: a file that has not been gofmt'd yet would otherwise keep the old alias and fail to compile after the call-site rewrite. docs/README.md documented a plural categories field that no page uses, and had a typo in the order sentence.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes OSS-4186.
A single place to read v1 to v2 migration instructions, at
/docs/migrating-to-v2/overview/, mirroring the v1 guide.Until now the only guidance was the beta.1 release notes plus
docs/v2-import-map.md, which is a design artifact (it has an accounting section and a decision log) rather than something to hand a user.Pages
overviewrewriting-importsgo.modimport-mapbehaviour-changesk8schanges the compiler will not catchThe split follows the work: steps 1 to 3 are compile errors, so "if it builds, you are done". Step 4 is the only part that needs reading, so it gets its own page rather than being buried.
Two things the guide calls out that a path table alone would not:
awsbecause plainawsis the SDK. The symbol relocations produce a compile error there, so it needs a human.corecollapse has to run before the/v2suffix rule, or it rewrites paths that do not exist.Also links forward from the v1 overview, and renumbers
04_communityto05_communityso ordering stays contiguous. Permalinks come from front mattercategory, so no URLs change.Note
The import map says "the codemod handles both" for the package renames, but no codemod exists in the repo. I wrote out the sed commands instead. Worth either shipping a codemod or dropping that sentence.
Summary by CodeRabbit