diff --git a/com.unity.netcode.gameobjects/Documentation~/TableOfContents.md b/com.unity.netcode.gameobjects/Documentation~/TableOfContents.md
index 24219a83e5..e351f13683 100644
--- a/com.unity.netcode.gameobjects/Documentation~/TableOfContents.md
+++ b/com.unity.netcode.gameobjects/Documentation~/TableOfContents.md
@@ -1,5 +1,6 @@
 * [Netcode for GameObjects package](index.md)
 * [Install](install.md)
+* [Upgrade from 2.x to 3.x](upgrade-guide.md)
 * [Get started](tutorials/get-started-with-ngo.md)
   * [Client-server quickstart](tutorials/get-started-with-ngo.md)
   * [Distributed authority quickstart](da-quickstart.md)
diff --git a/com.unity.netcode.gameobjects/Documentation~/upgrade-guide.md b/com.unity.netcode.gameobjects/Documentation~/upgrade-guide.md
new file mode 100644
index 0000000000..c1e0a62f11
--- /dev/null
+++ b/com.unity.netcode.gameobjects/Documentation~/upgrade-guide.md
@@ -0,0 +1,131 @@
+# Upgrade from 2.x to 3.x
+
+Update your project for the Unity Editor, assembly definition, dependency, and API changes that Netcode for GameObjects 3.x introduces.
+
+Version 3.x of Netcode for GameObjects raises the minimum Unity Editor version, renames the Editor assembly definitions, and turns several obsolete API warnings into compile errors. Refer to the following sections for the changes that affect your project and the steps to take for each one.
+
+> [!WARNING]
+> The API updater modifies your files in place. Commit or back up your work before you update your project.
+
+## Prerequisites
+
+Before you upgrade, make sure that your project meets the following requirements:
+
+- Unity Editor version 6.7 or later. If your project uses an earlier Editor version, either stay on version 2.x or upgrade the Editor first.
+- Target platforms that support Burst and Entities.
+
+Version 3.x depends on the Netcode for Entities package (`com.unity.netcode`), which in turn depends on the Entities packages (`com.unity.entities`, `com.unity.collections`, `com.unity.burst`, and `com.unity.mathematics`). Installing version 3.x adds these packages to your project. As a result, your project contains more packages, and its build times increase.
+
+## Upgrade your project to Unity 6000.7 or higher
+
+To upgrade an existing project from version 2.x to version 3.x, follow these steps:
+
+1. Back up your project, or commit your work to source control.
+2. Open your project with the Unity Editor version 6.7 or later.
+3. Your project's manifest will be updated with NGO v3.x.x prior to the API updater running.
+4. The API updater should catch any issues and ask if you want to allow it to make changes to your script(s).
+5. If you allow the API updater to make changes for you, then it should auto-update your project's scripts with the correct namespace changes.
+6. If you do not allow the API updater to make changes for you, then the editor will enter safe mode. Open the **Console** window to review the remaining compile errors and resolve the errors. (_[Review the Update Editor assembly definition references section below.](#update-editor-assembly-definition-references)_).
+   
+After the API updater finishes and you resolve the compile errors, your project compiles against version 3.x. If the API updater doesn't resolve every reference, refer to [Continue an incomplete API update](#continue-an-incomplete-api-update).
+
+_** If, at any point, you decide to downgrade to the editor version you were using prior to updating to 6.7, then make sure to restore or delete the packages-lock.json file (_assures you are not referencing 6.7 specific packages_), restore your backed up version, and delete your Library folder prior to opening your project with the editor version you were using prior to upgrading to 6.7._
+
+### Continue an incomplete API update
+
+The API updater doesn't always complete its work in one pass. If the update is incomplete, trigger compilation again so that the API updater can continue to apply its changes.
+
+If you experience issues with the API updater, report the issue through the [Unity bug submission process](https://unity3d.com/unity/qa/bug-reporting).
+
+## Update Editor assembly definition references
+
+Version 3.x renames the Editor assembly definitions to the `Unity.Netcode.GameObjects.*` form:
+
+| **Original name** | **New name** |
+| --- | --- |
+| `Unity.Netcode.Editor` | `Unity.Netcode.GameObjects.Editor` |
+| `Unity.Netcode.Editor.CodeGen` | `Unity.Netcode.GameObjects.Editor.CodeGen` |
+| `Unity.Netcode.PackageChecker.Editor` | `Unity.Netcode.GameObjects.PackageChecker.Editor` |
+| `Unity.Netcode.Editor.Tests` | `Unity.Netcode.GameObjects.Editor.Tests` |
+
+If your own Editor assemblies reference any of these assembly definitions by name, update the reference to the new name. The API updater migrates references to the moved Editor namespace types for you.
+
+Version 3.x doesn't change the runtime assembly definition (`Unity.Netcode.Runtime`) or the runtime `Unity.Netcode` namespace. Runtime scripts that only use `using Unity.Netcode;` need no changes for this rename.
+
+## Replace obsolete APIs that now raise compile errors
+
+Version 2.x marks several APIs with `[Obsolete]` and raises a warning for each one. Version 3.x raises a compile error instead. Version 3.x doesn't remove the members, so the error message points you to the replacement in each case.
+
+### APIs with replacements
+
+Replace each of the following APIs with its listed replacement:
+
+| **Original API** | **Replacement** |
+| --- | --- |
+| `NetworkObject.IsSceneObject` | `NetworkObject.InScenePlaced` |
+| `[ServerRpc(RequireOwnership = true)]` | `[Rpc(SendTo.Server, InvokePermission = RpcInvokePermission.Owner)]` |
+| `[ServerRpc(RequireOwnership = false)]` | `[Rpc(SendTo.Server, InvokePermission = RpcInvokePermission.Everyone)]` |
+| `ConnectionAddressData.ServerEndPoint` (`ParseNetworkEndpoint`) | `NetworkEndpoint.Parse` on the `Address` field |
+| `NetworkBehaviourEditor.GetRootParentTransform(Transform)` | `transform.root` |
+
+The `RequireOwnership` field applies to `ServerRpc` and the other remote procedure call (RPC) attributes. Use `InvokePermission` in its place. For more information, refer to [RPCs](advanced-topics/message-system/rpc.md).
+
+### Replace command-line argument lookups
+
+Version 3.x raises a compile error for both `CommandLineOptions.Instance` and the `CommandLineOptions.GetArg` instance method, so a typical `Instance.GetArg` call needs a full rewrite rather than a rename. Use the static `CommandLineOptions.TryGetArg` method, which reports whether it found the argument and returns the value through an `out` parameter:
+
+```csharp
+// Version 2.x
+var value = CommandLineOptions.Instance.GetArg("--myArg");
+if (value != null)
+{
+    // Use value.
+}
+
+// Version 3.x
+if (CommandLineOptions.TryGetArg("--myArg", out var value))
+{
+    // Use value.
+}
+```
+
+### APIs without replacements
+
+Remove your use of each of the following APIs:
+
+- `NetworkObject.SetSceneObjectStatus(bool)`: version 3.x computes the in-scene status during the build, so remove these calls.
+- `UnityTransport.InitialMaxSendQueueSize`: version 3.x determines the maximum send queue size dynamically, so remove your use of this constant. You can still set `MaxSendQueueSize` using C# scripts if you need to.
+- `UnityTransport.DebugSimulator` and `UnityTransport.SetDebugSimulatorParameters(...)`: version 3.x no longer supports these members, and they have no effect. Use the [Network Simulator tool](https://docs.unity3d.com/Packages/com.unity.multiplayer.tools@latest?subfolder=/manual/network-simulator) from the Multiplayer Tools package instead.
+- `NotListeningException`: version 3.x no longer uses this exception.
+- The obsolete list and property on `BufferedLinearInterpolator`, the obsolete property on `NetworkList`, and the obsolete method on `NetworkSpawnManager`: version 3.x no longer supports these members.
+
+### Remove directives that disable obsolete warnings
+
+If you disabled the version 2.x warnings with `#pragma warning disable CS0618`, remove that directive and apply the replacements in the previous sections. You can't disable the error form (`CS0619`) with `#pragma warning disable`.
+
+## Behavior changes that don't require code edits
+
+The following changes don't require code edits, but they change runtime behavior. Review them if your project depends on the behavior of version 2.x.
+
+### Position synchronization uses a higher resolution
+
+In version 3.x, `NetworkTransform.UseHalfFloatPrecision` synchronizes position at a resolution of approximately 1 mm, regardless of how far a GameObject has traveled. In version 2.x, the resolution might degrade to approximately 3 cm. The change doesn't increase bandwidth, but a project that uses `NetworkTransform.UseUnreliableDeltas` sends full-precision position updates more often. For more information, refer to [NetworkTransform](components/helper/networktransform.md).
+
+### Interpolation smoothing is frame rate independent
+
+In version 2.x, the `Lerp` and `SmoothDampening` interpolation types smooth by different amounts at different frame rates, because Netcode for GameObjects applies smoothing per frame instead of over time. Version 3.x applies smoothing over time, so results at 60 frames per second (fps) stay the same as in version 2.x, and results at other frame rates differ.
+
+## Netcode for Entities integration
+
+> [!NOTE]
+> This integration is experimental, so it's not ready for production use. The features and documentation for this integration might change before it's verified for release.
+
+Version 3.x introduces the foundations of the unified GameObject layer for Netcode for Entities, known as the hybrid prefab concept. Version 3.x doesn't enable this integration by default for standard GameObject workflows. Standard `NetworkBehaviour`, `NetworkVariable`, and RPC workflows work the same as in version 2.x.
+
+## Additional resources
+
+- [Install Netcode for GameObjects](install.md)
+- [Netcode for Entities](https://docs.unity3d.com/Packages/com.unity.netcode@latest)
+- [NetworkObject](components/core/networkobject.md)
+- [NetworkTransform](components/helper/networktransform.md)
+- [RPCs](advanced-topics/message-system/rpc.md)