fix: correct stale "v1" package name in types.NewPackage calls and clarify upgrade guide

Signed-off-by: JP Schoombee <jpschoombee@gmail.com>

Author: jschoombee

docs/upjet-v2-upgrade.md

@@ -135,11 +135,14 @@ github.com/crossplane/upjet/ => github.com/crossplane/upjet/v2/
 >
 > 1. In `go.mod` bump `github.com/crossplane/crossplane-runtime/v2` to
 >    `v2.3.x` and add a direct require on
->    `github.com/crossplane/crossplane/apis/v2 v2.3.x`. Run `go mod tidy`.
+>    `github.com/crossplane/crossplane/apis/v2 v2.3.x`. Run `go mod tidy`
+>    and confirm it succeeds before proceeding — the build will not compile
+>    without the new direct dependency in place.
 > 2. Run `make generate`. Upjet's code generator emits the new package
 >    path and type names automatically for all your generated `zz_*.go`
->    files. Any hand-written code that imports `crossplane-runtime/v2/apis/common/{v1,v2}`
->    needs its import path updated to the consolidated package.
+>    files. Any hand-written code that imports
+>    `crossplane-runtime/v2/apis/common/{v1,v2}` needs its import path
+>    updated to the consolidated package.
 >
 > If you have generated `zz_*.go` files committed and you're not ready to
 > regenerate yet, you can also bulk-rewrite the import paths and the two
@@ -180,6 +183,11 @@ type ProviderConfig struct {
 
 ### `apis` directory
 
+> **Note:** The import paths in the examples below are for the base
+> Upjet v1 → v2 migration (crossplane-runtime v1 module). If you are
+> already on Upjet v2 and only bumping to crossplane-runtime v2.3.x, see
+> the callout above instead.
+
 - In `apis/namespaced/v1beta1/types.go`, make sure that `ProviderConfigUsage` type inlines `xpv2.TypedProviderConfigUsage`
 
 ```diff

pkg/types/reference.go

@@ -31,43 +31,43 @@ const (
 // Types to use from by reference generator.
 var (
 	typeReferenceField types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "Reference", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "Reference", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 	typeSelectorField types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "Selector", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "Selector", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 	typeSecretKeySelector types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "SecretKeySelector", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "SecretKeySelector", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 	typeSecretReference types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "SecretReference", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "SecretReference", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 	typeLocalSecretReference types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "LocalSecretReference", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "LocalSecretReference", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 	typeLocalSecretKeySelector types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "LocalSecretKeySelector", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "LocalSecretKeySelector", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 	typeNamespacedReferenceField types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "NamespacedReference", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "NamespacedReference", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)
 
 	typeNamespacedSelectorField types.Type = types.NewNamed(
-		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v1"), "NamespacedSelector", nil),
+		types.NewTypeName(token.NoPos, types.NewPackage(PackagePathXPCommonAPIs, "v2"), "NamespacedSelector", nil),
 		types.NewStruct(nil, nil),
 		nil,
 	)