integrate migration plan guidance

Author: yaahc

posts/inside-rust/2021-05-15-What-the-error-handling-project-group-is-working-towards.md

@@ -224,7 +224,9 @@ To resolve this issue, project error handling recently created a guideline for [
 
 **An error type with a source error should either return that error via `source` or include that source's error message in it's own `Display` output, but never both.**
 
-We figure the default will be to return errors via source, so that source errors can be reacted to via `downcast` when appropriate. In coming up with this recommendation we had to figure out what the `Error` trait's primary role is in Rust. After discussing it with the library team we concluded that reporting should be treated as the primary role, and that reacting via `downcast` should come second when designing error types.
+We figure the default will be to return errors via source. That way source errors can be reacted to via `downcast` when appropriate. This is particularly important for libraries that are changing existing public error types. For these libraries removing an error from `source` is a breaking change that isn't detected at compile time, making a major version bump likely insufficient. For more details check out our migration plan suggestion: [rust-lang/project-error-handling#44](https://github.com/rust-lang/project-error-handling/issues/44).
+
+In coming up with this recommendation we had to figure out what the `Error` trait's primary role is in Rust. After discussing it with the library team we concluded that reporting should be treated as the primary role, and that reacting via `downcast` should come second when designing error types. Generally these needs are not in conflict, but it is possible for issues to come up. For example, when working with transparent error types that forward all methods to an inner error type. When these types follow this guideline the inner error type is skipped over and is never made available for `downcast`ing.
 
 This recommendation only applies for error types that are exposed as part of library APIs. Internal errors in libraries or and applications can do whatever they want, but as soon as they need to be integrated into other crates by 3rd party users it's important that errors follow a consistent style. If you're interested in our rationale or have any comments please check out our github issue on the topic: [rust-lang/project-error-handling#27](https://github.com/rust-lang/project-error-handling/issues/27).