docs: add avro upgrade notes for arrow-avro migration

Author: getChan

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

@@ -472,3 +472,46 @@ Now:
 +-------+
 0 row(s) fetched.
 ```
+
+### Avro API, feature, and decoding changes
+
+As part of the Avro reader migration (see [#17861]), DataFusion now delegates
+Avro-to-Arrow type decoding to `arrow-avro` (aligned with `arrow-avro` semantics),
+and several Avro-related APIs/feature wiring changed:
+
+- `DataFusionError::AvroError` has been removed.
+- `From<apache_avro::Error> for DataFusionError` has been removed.
+- Avro crate re-export changed:
+  - Before: `datafusion::apache_avro`
+  - After: `datafusion::arrow_avro`
+- Cargo feature wiring changed:
+  - `datafusion` crate `avro` feature no longer enables `datafusion-common/avro`
+  - `datafusion-proto` crate `avro` feature no longer enables `datafusion-common/avro`
+- **Avro datatype interpretation now follows `arrow-avro` behavior.** Notable effects:
+  - Avro `string` logical values are read as Arrow `Binary` in DataFusion Avro scans
+  - Avro `timestamp-*` logical types are read as UTC timezone-aware Arrow timestamps
+    (`Timestamp(..., Some("+00:00"))`)
+  - Avro `local-timestamp-*` logical types remain timezone-naive
+    (`Timestamp(..., None)`)
+
+**Who is affected:**
+
+- Users matching on `DataFusionError::AvroError`
+- Users importing `datafusion::apache_avro`
+- Users depending on the old `datafusion-common/avro` feature wiring
+- Users relying on DataFusion-specific Avro decoding behavior (especially `string`
+  and timestamp logical types)
+
+**Migration guide:**
+
+- Replace `datafusion::apache_avro` imports with `datafusion::arrow_avro`.
+- Update error handling code that matches on `DataFusionError::AvroError` to use
+  the current error surface.
+- If you depend on Avro feature propagation, update Cargo feature expectations:
+  `datafusion`/`datafusion-proto` `avro` no longer enables `datafusion-common/avro`.
+- Review Avro table schemas and add explicit casts where needed for binary-backed
+  string values (for example, `CAST(binary_col AS VARCHAR)`).
+- Validate timestamp handling where timezone semantics matter:
+  `timestamp-*` is UTC timezone-aware, while `local-timestamp-*` is timezone-naive.
+
+[#17861]: https://github.com/apache/datafusion/pull/17861