Add upgrade guide for partition_statistics signature change

Author: asolimando

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

@@ -380,3 +380,93 @@ impl Default for MyTreeNode {
     }
 }
 ```
+
+### `ExecutionPlan::partition_statistics` now accepts a `StatisticsContext`
+
+`ExecutionPlan::partition_statistics` now takes an additional
+`ctx: &StatisticsContext` parameter that carries pre-computed child statistics
+and additional context for statistics computation.
+
+**Before:**
+
+```rust,ignore
+fn partition_statistics(&self, partition: Option<usize>) -> Result<Arc<Statistics>> {
+    // Leaf node
+    Ok(Arc::new(Statistics::new_unknown(&self.schema())))
+}
+```
+
+**After:**
+
+```rust,ignore
+fn partition_statistics(
+    &self,
+    partition: Option<usize>,
+    _ctx: &StatisticsContext,
+) -> Result<Arc<Statistics>> {
+    // Leaf node: ignore ctx, return own stats
+    Ok(Arc::new(Statistics::new_unknown(&self.schema())))
+}
+```
+
+**Who is affected:**
+
+- Users who implement custom `ExecutionPlan` nodes
+- Users who call `partition_statistics` directly
+
+**Migration guide:**
+
+For **implementations**, add the `ctx: &StatisticsContext` parameter. Leaf nodes
+that do not have children can use `_ctx` (ignored). Non-leaf nodes that
+previously called `self.input.partition_statistics(partition)?` to obtain child
+statistics can use `ctx.child_stats()[0]` instead (or `ctx.child_stats()[i]`
+for multi-child operators like joins):
+
+```rust,ignore
+// Before (non-leaf):
+fn partition_statistics(&self, partition: Option<usize>) -> Result<Arc<Statistics>> {
+    let child_stats = self.input.partition_statistics(partition)?;
+    // ... transform child_stats ...
+}
+
+// After (non-leaf):
+fn partition_statistics(
+    &self,
+    _partition: Option<usize>,
+    ctx: &StatisticsContext,
+) -> Result<Arc<Statistics>> {
+    let child_stats = Arc::clone(&ctx.child_stats()[0]);
+    // ... transform child_stats ...
+}
+```
+
+Operators that **merge or repartition** their input (e.g., coalesce, sort
+without partition preservation, sort-preserving merge) always need overall
+child statistics regardless of which output partition is requested. These
+operators should call `compute_statistics` with `None` on the relevant
+child instead of using `ctx.child_stats()`:
+
+```rust,ignore
+// Operator that merges all input partitions into one:
+fn partition_statistics(
+    &self,
+    _partition: Option<usize>,
+    _ctx: &StatisticsContext,
+) -> Result<Arc<Statistics>> {
+    compute_statistics(self.input.as_ref(), None)
+}
+```
+
+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)?;
+```