docs/migration: add advice to impl both versions, add e-h-compat

Author: Dirbaio

docs/migrating-from-0.2-to-1.0.md

@@ -19,6 +19,8 @@
 - [Removed blanket implementations](#removed-blanket-implementations)
 - [Cargo Features](#cargo-features)
 - [Companion crates](#companion-crates)
+- [Supporting both 0.2 and 1.0 in the same HAL](#supporting-both-02-and-10-in-the-same-hal)
+- [`embedded-hal-compat`](#embedded-hal-compat)
 
 ## Overview and reasoning
 
@@ -372,3 +374,59 @@ The `embedded-hal` project now spans several crates, where some functionality ha
 | [embedded-io-async](./embedded-io-async)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async) | [![Documentation](https://docs.rs/embedded-io-async/badge.svg)](https://docs.rs/embedded-io-async) | I/O traits, async version  |
 | [embedded-io-adapters](./embedded-io-adapters)       | [![crates.io](https://img.shields.io/crates/v/embedded-io-adapters.svg)](https://crates.io/crates/embedded-io-adapters) | [![Documentation](https://docs.rs/embedded-io-adapters/badge.svg)](https://docs.rs/embedded-io-adapters) | Adapters between the [`embedded-io`](https://crates.io/crates/embedded-io) and [`embedded-io-async`](https://crates.io/crates/embedded-io-async) traits and other IO traits (`std`, `tokio`, `futures`...)  |
 
+## Supporting both 0.2 and 1.0 in the same HAL
+
+It is strongly recommended that HAL implementation crates provide implementations for both the `embedded-hal` v0.2 and v1.0 traits.
+This allows users to use drivers using either version seamlessly.
+
+The way you do it is adding a dependency on both versions in `Cargo.toml` like this:
+
+```toml
+[dependencies]
+embedded-hal-02 = { package = "embedded-hal", version = "0.2.7", features = ["unproven"] }
+embedded-hal-1 = { package = "embedded-hal", version = "1.0" }
+```
+
+This allows you to refer to the v0.2 traits under the `embedded_hal_02` name, and the v1.0 traits under
+`embedded_hal_1`. Implement both versions on the same struct. For example, for an input pin:
+
+```rust
+/// The HAL's input pin struct
+struct Input {...}
+
+/// Implement the v0.2 traits on the struct.
+impl embedded_hal_02::digital::v2::InputPin for Input {
+    type Error = Infallible;
+
+    fn is_high(&self) -> Result<bool, Self::Error> {
+        ...
+    }
+
+    fn is_low(&self) -> Result<bool, Self::Error> {
+        ...
+    }
+}
+
+/// ... and implement the v1.0 traits on the *same* struct.
+impl embedded_hal_1::digital::ErrorType for Input {
+    type Error = Infallible;
+}
+
+impl embedded_hal_1::digital::InputPin for Input {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
+        ...
+    }
+
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
+        ...
+    }
+}
+```
+
+## `embedded-hal-compat`
+
+For HAL implementation crates that haven't been updated yet, [embedded-hal-compat](https://github.com/ryankurte/embedded-hal-compat)
+provides shims to support interoperability between `embedded-hal` v0.2 and v1.0.
+
+This allows using a driver requiring v1.0 with a HAL crate implementing only v0.2 or vice-versa, (generally) without alteration.
+See the [docs](https://docs.rs/embedded-hal-compat/) for examples.