Now that breaking changes are much more rare, and preceded by long discussion of how the breakage can be worked around, it may be worthwhile to provide a single document that lists:
- Summary of the change.
- Information that helps you identify that it is indeed this change that broke your code (e.g. the feature or function affected, or the compiler error messages mentioned).
- How to fix your code:
- If it’s a compile time error, how to rewrite the code to compile with the same semantics.
- If it’s a behavioral change, how to rewrite code to keep the old behavior.
This came up while talking to the developers of ares about the recent change to accept leading plus in integer parsing. If you don’t follow the Rust repo closely, it can be difficult to make sense of the
[breaking-change] commit messages and find the exact information that you need to fix your crate.
It could be as simple as a Markdown file in the repo. Since we don’t do as many breaking and behavioral changes any more, it may not be an undue burden to ask people to write a paragraph or two about their change in such a log. (Then again, we still cobble together the release notes on the day before the release…)