add to migration guide

Author: 2bndy5

docs/migration.md

@@ -46,6 +46,10 @@ There are overloaded functions that use a buffer instead:
 These eliminate the unnecessary 24 bits by only using the length of the buffer (`uint8_t*`)
 specified by `RF24::setAddressWidth()`.
 
+@see The `RF24::openWritingPipe(const uint8_t*)` is now deprecated in favor of the
+overloaded `RF24::stopListening(uint8_t*)` function.
+See the section below for more detail.
+
 > [!CAUTION]
 > The endianness (byte order) of a buffer is reversed compared to a 64-bit integer.
 > ```c
@@ -211,3 +215,63 @@ radio.clearStatusFlags(RF24_RX_DR);
 ```
 
 </td></tr></table>
+
+## openWritingPipe(const uint8_t*)
+
+> Deprecated since v1.5
+
+Originally, `RF24::openWritingPipe(const uint8_t*)` was just a compliment to
+`RF24::openReadingPipe()`.
+It changes the address on pipe 0 because that is the only pipe that can be
+used for transmitting.
+
+Unfortunately, there was a bug that prevented the given TX address from being
+persistent on pipe 0 if the user code also set an RX address to pipe 0.
+This bug would surface when switching between RX mode and TX mode (via
+`RF24::startListening()` and `RF24::stopListening()` respectively) or after
+`RF24::stopConstCarrier()`.
+As a result the TX address has to be cached on the `RF24` instance.
+Consequently, this solution does not fit well with the traditional order of
+setting up the radio.
+
+By overloading `RF24::stopListening(const uint8_t*)`, we are able to ensure proper radio
+setup without requiring certain functions are called in a certain order.
+
+- Use `RF24::stopListening(const uint8_t*)` to set the TX address and enter inactive TX mode.
+  `RF24::openReadingPipe()` can now (as of v1.5) be used in TX mode without consequence.
+- Use `RF24::stopListening()` to enter inactive TX mode without changing the TX address.
+
+> [!warning]
+> Avoid using pipe 0 for RX operations to improve performance and reliability.
+>
+> For implementation detail, see the source for `RF24::openReadingPipe()` and
+> `RF24::stopListening()`. Ultimately, the datasheet's Appendix A has a detailed
+> example outlining the order of a proper radio setup.
+
+<table><tr>
+<th>Old</th>
+<th>New (supported)</th>
+</tr><tr><td>
+
+```cpp
+// set TX address (pipe 0)
+radio.openWritingPipe(tx_address);
+
+// set RX address (pipe 1)
+radio.openReadingPipe(1, rx_address);
+
+// idle radio using inactive TX mode
+radio.stopListening();
+```
+
+</td><td>
+
+```cpp
+// set TX address (pipe 0)
+radio.stopListening(tx_address); // enters inactive TX mode
+
+// set RX address (pipe 1)
+radio.openReadingPipe(1, rx_address);
+```
+
+</td></tr></table>