docs: record the symbol moves and behaviour changes from the v2 beta

[james00012]

Follow-up to #1875. There is no v2 migration doc, and v2-import-map.md covers import paths only.

Gap

The map is marked FROZEN without qualification, which reads as "this is the whole migration". It is not. A user who runs the documented path rewrite gets clean imports and then eight compile errors, with nothing pointing at where those symbols went.

Change

Three additions to docs/v2-import-map.md:

• Symbols relocated during the v2 beta. The eight teststructure functions that moved to aws, k8s, packer and ssh in refactor(teststructure): drop aws, k8s, packer and ssh dependencies #1877, plus what deliberately stayed and why the churn is about 6% of call sites.
• A migration recipe. The qualifier swap, and the two cases where a blind find and replace goes wrong: the target module not yet imported, and files that bind plain aws to the AWS SDK and alias Terratest's.
• Behaviour changes. The ExternalIP preference from refactor(k8s): resolve node public IPs through an injectable lookup #1878 including the new FindNodeHostnameWithOptionsContext[E], and the RestConfig serialization error from fix(k8s): refuse to serialize KubectlOptions carrying a RestConfig #1879.

FROZEN is rescoped to import paths.

Every symbol in the table was checked against the merged code.

Summary by CodeRabbit

• Documentation
  • Updated the v2 import map to mark renamed packages as resolved and link beta symbol relocations.
  • Added migration guidance for moved functions, unchanged symbols, and qualifier or import updates.
  • Documented node address selection, including preference for external IP addresses.
  • Clarified options-aware node lookup behavior.
  • Documented serialization errors that may occur when using REST configuration with Kubernetes options.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d4befe2-39ad-41fc-a94b-d667c2bbd21f

📥 Commits

Reviewing files that changed from the base of the PR and between 18eb952 and 06962b8.

📒 Files selected for processing (1)

• docs/v2-import-map.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/v2-import-map.md

---

Walkthrough

The import map documents resolved Terratest v2 package renames, relocated functions, unchanged symbols, qualifier handling, node lookup behavior, and KubectlOptions serialization errors.

Changes

Terratest v2 migration documentation

Layer / File(s)	Summary
Import and symbol migration docs/v2-import-map.md	The import map records three resolved package renames and documents eight relocated functions, unchanged symbols, and qualifier handling.
Beta behavior guidance docs/v2-import-map.md	The guide documents ExternalIP node lookup behavior, options-aware lookup functions, and KubectlOptions.MarshalJSON errors for RestConfig.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• gruntwork-io/terratest#1836: Updates the same import map with Terratest v2 migration guidance.
• gruntwork-io/terratest#1841: Adds related import-path and package-renaming guidance in the same document.

Suggested reviewers: denis256, yhakbar

Poem

Imports move to version two,
Symbols settle where they’re due.
Nodes choose ExternalIP with care,
Serialization errors make issues clear.
The migration map keeps changes in view.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the documentation change for v2 beta symbol moves and behavior changes.
Description check	✅ Passed	The description clearly explains the gap, documents the changes, and states that the symbols were checked against merged code.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/v2-symbol-relocations

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}