Add upgrade guide for statistics_with_args migration

Author: asolimando

docs/source/library-user-guide/upgrading/55.0.0.md

@@ -96,3 +96,68 @@ as a supertrait:
 - pub trait QueryPlanner: Debug
 + pub trait QueryPlanner: Any + Debug
 ```
+
+### `ExecutionPlan::partition_statistics` deprecated in favor of `statistics_with_args`
+
+`ExecutionPlan::partition_statistics` is deprecated. A new method
+`statistics_with_args` accepts a `StatisticsArgs` parameter that bundles
+the partition index and a `StatisticsContext` carrying pre-computed child
+statistics and additional context for statistics computation.
+
+Existing implementations of `partition_statistics` continue to work unchanged.
+The default `statistics_with_args` delegates to the deprecated method, so no
+migration is required until the deprecated method is removed.
+
+**Who is affected:**
+
+- Users who implement custom `ExecutionPlan` nodes (recommended to migrate)
+- Users who call `partition_statistics` directly (recommended to switch to `compute_statistics`)
+
+**Migration guide:**
+
+For **implementations**, override `statistics_with_args` instead of
+`partition_statistics`. Leaf nodes that do not have children can ignore the
+context.
+
+Child statistics are looked up via `args.compute_child_statistics(child, partition)`.
+Use `args.partition()` for partition-preserving operators, or `None` for
+partition-merging operators that always need overall stats:
+
+```rust,ignore
+// Before:
+fn partition_statistics(&self, partition: Option<usize>) -> Result<Arc<Statistics>> {
+    let child_stats = self.input.partition_statistics(partition)?;
+    // ... transform child_stats ...
+}
+
+// After (partition-preserving):
+fn statistics_with_args(
+    &self,
+    args: &StatisticsArgs,
+) -> Result<Arc<Statistics>> {
+    let child_stats = args.compute_child_statistics(self.input.as_ref(), args.partition())?;
+    // ... transform child_stats ...
+}
+
+// After (partition-merging):
+fn statistics_with_args(
+    &self,
+    args: &StatisticsArgs,
+) -> Result<Arc<Statistics>> {
+    let child_stats = args.compute_child_statistics(self.input.as_ref(), None)?;
+    // ... transform child_stats ...
+}
+```
+
+For **callers**, replace direct calls with `compute_statistics`, which walks
+the plan tree bottom-up and threads child statistics through the context
+automatically:
+
+```rust,ignore
+use datafusion_physical_plan::compute_statistics;
+
+// Before:
+let stats = plan.partition_statistics(None)?;
+
+// After:
+let stats = compute_statistics(plan.as_ref(), None)?;