docs(v1): tighten migration overview after accuracy audit

Independent review of the overview surfaced several inaccuracies and
altitude problems. Rewrite to:

- Fix wrong AWS function names. The doc named NewS3UploaderWithSession
  and NewS3UploaderWithSessionE, neither of which exist. The actual
  four functions are NewS3Uploader, NewS3UploaderE, NewS3UploaderContext,
  and NewS3UploaderContextE.
- Drop the GCP compute receiver-method paragraph. That conversion
  happened in 2018, not for v1; there are no surviving deprecated free
  functions to migrate from.
- Replace the t.Context() example. Helpers take testing.TestingT, an
  interface that does not expose Context(); the example was misleading
  for callers passing the abstracted type. Default to context.Background()
  and mention t.Context() only as an option for *testing.T.
- Expand the affected-packages list to include http-helper, packer,
  docker, ssh, and oci.
- Soften the "wrappers forward to *Context* with context.Background()"
  blanket claim, which has at least one false case.

Cut altitude per a "don't stay too low level" instruction:

- Trim Azure highlights bullet list; the per-rename detail belongs in
  the Azure sub-guide which the overview already links to.
- Trim AWS section: drop the SDK service enumeration in favor of "every
  direct github.com/aws/aws-* dep was bumped".
- Replace the named per-rename "Other deprecations" list with a
  principled paragraph plus a pointer to running staticcheck/go vet,
  which surfaces the deprecation warnings with replacement guidance.

Add a Prerequisites section calling out Go 1.26+ and the cross-cloud
go mod tidy step. Add a one-line callout for the new GCP *WithClient
injection helpers (parallels the Azure note).

Author: james00012

docs/_docs/03_migrating-to-v1/overview.md

@@ -15,8 +15,15 @@ changes to the public API only happen in major releases (e.g. v2.0.0), per
 [semver](https://semver.org/). Renamed or replaced symbols stay around as
 deprecated aliases inside v1; full removal is deferred to v2.
 
-This page lists what changed at the v0.x to v1.0.0 boundary and points at
-the per-service guides where the change set is large.
+This page is the orientation map for v0.x to v1.0.0. It tells you what
+shape the changes take and where to look; the per-service guides hold the
+mechanical details.
+
+## Prerequisites
+
+- **Go 1.26 or newer.** v1.0.0 raised the minimum.
+- After upgrading, run `go mod tidy` from the directory that holds your
+  test module's `go.mod`. The AWS, Azure, and GCP SDK pins all moved.
 
 ## Function naming conventions
 
@@ -35,28 +42,29 @@ Two independent suffixes:
 - **`E` suffix.** Long-standing Terratest convention. Use the bare name
   (`Apply`) when you want any failure to fail the test, and the `E`
   variant (`ApplyE`) when you want the error back to assert on it or
-  retry. Both variants exist for almost every helper.
+  retry.
 - **`Context` suffix.** Added in v1. Takes an explicit `context.Context`
   as the second argument so callers can plumb timeouts, cancellation,
-  and tracing through. The non-`Context` variants are now deprecated and
-  internally call the `*Context*` variant with `context.Background()`.
+  and tracing through. The non-`Context` variants are now deprecated
+  in favor of their `*Context*` counterparts.
 
 The preferred v1 call is `FooContext` (or `FooContextE`). For example,
-prefer `terraform.ApplyContext(t, ctx, opts)` over `terraform.Apply(t, opts)`.
+prefer `terraform.ApplyContext(t, ctx, opts)` over
+`terraform.Apply(t, opts)`.
+
+A small number of helpers do not yet expose all four variants (some
+packages added `Context` and dropped the bare `Foo` form, others have
+not grown a `Context` variant at all). Trust godoc and the deprecation
+warnings over the table when they disagree.
 
 ## Migrating to the `Context` variants
 
 The Context migration is the single largest source of deprecation
-warnings you will see when upgrading. Every helper that runs an external
-command, makes an SDK call, or sleeps got a `*Context` / `*ContextE`
-companion. The non-`Context` variants compile and behave identically;
-they just emit a `// Deprecated:` godoc warning and forward to the
-`*Context*` variant with `context.Background()`.
-
-Affected packages (rough scope):
-
-- `modules/terraform`, `modules/helm`, `modules/dns-helper`
-- `modules/k8s`, `modules/aws`, `modules/azure`, `modules/gcp`
+warnings you will see when upgrading. It touches nearly every helper
+package: `terraform`, `helm`, `dns-helper`, `http-helper`, `packer`,
+`docker`, `ssh`, `oci`, `k8s`, `aws`, `azure`, `gcp`. The non-`Context`
+variants compile and behave the same as before; they just emit a
+`// Deprecated:` godoc warning.
 
 Mechanical migration:
 
@@ -66,113 +74,91 @@ out := terraform.Apply(t, options)
 out, err := terraform.ApplyE(t, options)
 
 // After
-ctx := t.Context() // Go 1.24+; or context.Background() / context.WithTimeout(...)
+ctx := context.Background() // or context.WithTimeout(...) for cancellation
 out := terraform.ApplyContext(t, ctx, options)
 out, err := terraform.ApplyContextE(t, ctx, options)
 ```
 
-The order of arguments in `*Context*` variants is always
-`(t, ctx, ...originalArgs)`. If you do not need cancellation or
-timeouts yet, passing `context.Background()` is fine and gives you the
-same behavior as the deprecated wrapper while moving you off the
-deprecation warning.
+The `*Context*` variants always take `(t, ctx, ...originalArgs)`. If
+you do not need cancellation or timeouts, `context.Background()` gives
+you the same behavior as the deprecated wrapper. When `t` is
+`*testing.T` (Go 1.24+), `t.Context()` is an even better default
+because it ties the context lifetime to the test.
 
-You can do this incrementally. The deprecated wrappers will keep working
-for the entire v1 line; they only disappear in v2.
+You can do this incrementally. The deprecated wrappers will keep
+working for the entire v1 line; they only disappear in v2.
 
 ## What changed by service
 
 ### Azure
 
-The largest set of breaking changes. The whole `modules/azure` package
-was moved from the archived `services/...` SDK to the actively maintained
-`sdk/resourcemanager/...` SDK, plus a handful of naming cleanups landed
-in the same release. See [Azure modules](./azure/) for the full migration
-guide. Highlights:
-
-- `services/...` imports become `sdk/resourcemanager/.../arm<service>`.
-- Resource fields move under `.Properties`.
-- Iterator-based list calls become pagers.
-- 8 `Get*ClientE` getters were removed; use the `Create*ClientE`
-  replacements that have been around for a while.
-- 4 `CreateNew*ClientE` factories were renamed to `Create*ClientE` (the
-  old names remain as deprecated aliases).
-- `NsgRuleSummary.SourceAdresssPrefixes` (triple-s typo) renamed to
-  `SourceAddressPrefixes`.
-- New `*WithClient` functions accept a pre-built SDK client for
-  injection in unit tests.
+The largest set of breaking changes by far. The whole `modules/azure`
+package was moved from the archived `services/...` SDK to the actively
+maintained `sdk/resourcemanager/...` SDK, plus a handful of naming
+cleanups. Updating imports and the resulting compile errors is the bulk
+of the work; per-service tables and a search-and-replace cheatsheet are
+in [Azure modules](./azure/).
 
 ### AWS
 
-`modules/aws/s3.go` migrated off the deprecated `s3/manager` package onto
-`s3/transfermanager`. Four exported functions changed return type:
-
-- `NewS3Uploader`
-- `NewS3UploaderE`
-- `NewS3UploaderWithSession`
-- `NewS3UploaderWithSessionE`
-
-These now return `*transfermanager.Client` instead of
-`*manager.Uploader`. The call shape moves from
+`modules/aws/s3.go` migrated off the deprecated
+`s3/manager` package onto `s3/transfermanager`. Four exported functions
+that returned `*manager.Uploader` now return `*transfermanager.Client`:
+`NewS3Uploader`, `NewS3UploaderE`, `NewS3UploaderContext`, and
+`NewS3UploaderContextE`. The call shape moves from
 `uploader.Upload(ctx, &s3.PutObjectInput{...})` to
-`client.UploadObject(ctx, &transfermanager.UploadObjectInput{...})`. The
-input and output types live in
+`client.UploadObject(ctx, &transfermanager.UploadObjectInput{...})`,
+with the input/output types under
 `github.com/aws/aws-sdk-go-v2/feature/s3/transfermanager`.
 
-All other AWS SDK v2 service deps (acm, autoscaling, cloudwatchlogs,
-dynamodb, ec2, ecr, ecs, iam, kms, lambda, rds, route53, s3,
-secretsmanager, sns, sqs, ssm, sts, config, credentials) were bumped to
-the versions current at v1.0.0 cut. If your tests import those SDKs
-directly, run `go mod tidy` after upgrading Terratest.
+Every direct `github.com/aws/aws-*` dependency was bumped to the
+versions current at the v1.0.0 cut. If your tests import the AWS SDKs
+directly, expect to run `go mod tidy` and resolve a small number of
+type renames at the SDK level.
 
 ### GCP
 
 `modules/gcp/pubsub.go` moved from `cloud.google.com/go/pubsub` (v1) to
-`cloud.google.com/go/pubsub/v2`. The v1 client is deprecated upstream and
-trips `staticcheck` SA1019.
-
-The shape of the wrapper functions in `modules/gcp` is unchanged, but
-callers that drove the underlying client directly need to switch from
-`client.Topic("name")` / `client.Subscription("name")` handles to
-`TopicAdminClient` / `SubscriptionAdminClient` calls that take fully
-qualified resource names (`projects/<id>/topics/<name>`).
-
-`modules/gcp/compute.go` also moved several free functions onto receiver
-methods of `Instance`, `ZonalInstanceGroup`, and `RegionalInstanceGroup`
-(e.g. `GetPublicIP(t, instance)` becomes `instance.GetPublicIP(t)`). The
-free-function forms are kept as deprecated wrappers; switch when
-convenient.
+`cloud.google.com/go/pubsub/v2`. The wrapper functions in `modules/gcp`
+are unchanged in shape, but callers that drove the underlying client
+directly need to switch from `client.Topic("name")` /
+`client.Subscription("name")` handles to `TopicAdminClient` /
+`SubscriptionAdminClient` calls that take fully qualified resource
+names (`projects/<id>/topics/<name>`).
+
+A new family of `*WithClient` helpers was added across `modules/gcp`
+(compute, oslogin, region, pubsub, storage, cloudbuild, gcr) so tests
+can inject a pre-built SDK client. This parallels the Azure
+`*WithClient` change and is purely additive.
 
 ### Kubernetes
 
-`GetKubernetesClientFromOptionsContextE` no longer falls back silently to
-`rest.InClusterConfig()` when an explicit kubeconfig path or context
-fails to load. It now returns the underlying `LoadAPIClientConfigE`
-error.
+`GetKubernetesClientFromOptionsContextE` no longer falls back silently
+to `rest.InClusterConfig()` when an explicit kubeconfig path or
+context fails to load. It now returns the load error.
 
-This was a silent-failure footgun: a typo in `KubectlOptions.ConfigPath`
-would cause tests to run against the test runner's in-cluster identity
-(potentially a different cluster) with no error. If you relied on that
-fallback, set `KubectlOptions.InClusterAuth = true` to opt in
-explicitly.
+This was a silent-failure footgun: a typo in
+`KubectlOptions.ConfigPath` would cause tests to run against the test
+runner's in-cluster identity (potentially a different cluster) with no
+error returned. If you relied on the fallback, set
+`KubectlOptions.InClusterAuth = true` to opt in explicitly.
 
 ## Other deprecations you can defer
 
-A handful of smaller renames also landed with `// Deprecated:` aliases:
-
-- `modules/azure`: `CreateNew*Client*` factories deprecated in favor of
-  `Create*Client*` (the redundant `New` is dropped).
-- `modules/ssh`: `SshSession` and `SshConnectionOptions` renamed to
-  `SSHSession` and `SSHConnectionOptions` (Go-idiomatic acronym
-  casing). The old names remain as deprecated type aliases.
-- `modules/terraform`: a few legacy spellings (e.g. `CtyJsonOutput` →
-  `CtyJSONOutput`).
-- `modules/test-structure`: SSH-key and artifact-ID save/load helpers
-  picked up consistent names (`SaveSSHKeyPair`, `LoadSSHKeyPair`,
-  `SaveArtifactID`, `LoadArtifactID`).
-
-These are pure renames: the old names forward to the new ones and stay
-in the v1 line.
+A large set of legacy spellings picked up Go-idiomatic replacements in
+v1, all preserved as deprecated aliases. Most follow common acronym
+casing (`Id` → `ID`, `Ip` → `IP`, `Json` → `JSON`, `Url` → `URL`,
+`Ssh` → `SSH`, `Gcp` → `GCP`); a few drop redundant prefixes (Azure's
+`CreateNew*Client*` becomes `Create*Client*`); and a few rename for
+clarity (e.g. `SaveAmiId` / `LoadAmiId` became
+`SaveArtifactID` / `LoadArtifactID` to reflect that the helpers are
+not AMI-specific).
+
+You do not need to track these one by one. Run `go vet` or
+`staticcheck` against your test module after upgrading; the deprecated
+aliases all carry `// Deprecated:` annotations and the linter will
+list them with the replacement to use. Aliases stay for the v1 line
+and are removed in v2.
 
 ## Need help