Add migration guide

Author: Jondolf

migration-guides/0.5-to-main.md

@@ -6,6 +6,27 @@ since the latest release. These guides are evolving and may not be polished yet.
 See [migration-guides/README.md](./README.md) and existing entries for information about Avian's
 migration guide process and what to put here.
 
+## Broad Phase Rework
+
+PR [#927](https://github.com/avianphysics/avian/pull/927) overhauled broad phase collision detection
+to use a Bounding Volume Hierarchy (BVH).
+
+`BroadPhasePlugin` has been replaced by two plugins:
+
+- `BroadPhaseCorePlugin`: Sets up resources, system sets, and diagnostics required for broad phase collision detection.
+- `BvhBroadPhasePlugin`: Implements a broad phase using a BVH to efficiently find overlapping AABBs.
+
+The latter can be swapped out for a custom broad phase implementation if desired.
+See the documentation of the `broad_phase plugin for more information.
+
+The `BroadPhaseSystems::UpdateStructures` system set has also been removed.
+The BVH acceleration structures are updated by the `ColliderTreePlugin`,
+in `ColliderTreeSystems::UpdateAabbs`.
+
+Contact pair creation order can be different from before due to the new broad phase algorithm,
+resulting in slightly changed behavior (but you should not rely on a specific contact order anyway).
+The order should still be deterministic across runs, given the same inputs.
+
 ## `ReadRigidBodyForces` and `WriteRigidBodyForces`
 
 PR [#908](https://github.com/avianphysics/avian/pull/908) introduced two new traits: `ReadRigidBodyForces` and `WriteRigidBodyForces`, and `RigidyBodyForces` is now defined as: