diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md
index 888366622..c810a0831 100644
--- a/esp-hal/MIGRATING-0.22.md
+++ b/esp-hal/MIGRATING-0.22.md
@@ -326,6 +326,29 @@ To avoid abbreviations and contractions (as per the esp-hal guidelines), some er
 + Error::ZeroLengthInvalid
 ```
 
+## I2C Configuration changes
+
+The timeout field in `Config` changed from `Option<u32>` to a dedicated `Timeout` enum.
+
+```diff
+- timeout: Some(10)
++ timeout: Timeout::BusCycles(10)
+```
+
+or (ESP32, ESP32-S2)
+
+```diff
+- timeout: None
++ timeout: Timeout::Max
+```
+
+or (other chips)
+
+```diff
+- timeout: None
++ timeout: Timeout::Disabled
+```
+
 ## The crate prelude has been removed
 
 The reexports that were previously part of the prelude are available through other paths: