Reading a changelog like a lawyer

Every release note has lines about new features, and lines about things that will change under you. Three kinds of the second sort are worth scanning first, and they usually hide in the same places every release.

Here are the three lines to scan, using Rust 1.99.0 as the example.

The lines that mention a hard error. These are the quietest break in any release. A lint becomes an error. In Rust 1.99, no_mangle_generic_items was upgraded into a hard error. If your code puts #[no_mangle] on a generic item, it no longer compiles, and an allow attribute will not silence it. Scan for the hard errors before you scan for new features.

The lines that say “changed” or “adjusted.” These are the semantic shifts that leave your compile intact but change what your program does. In Rust 1.99, the behavior of an exhausted RangeInclusive changed: its start() and end() may return different values, and using such a range as a slice index may behave differently. Your code still compiles. It just does something slightly different. These are the hardest to catch because there is no red text.

The lines that say “deprecated” or “disabled by default.” Rust 1.99 fully deprecated the legacy integral modules, so std::i32::MAX now warns and should be i32::MAX. A deprecation is a signal that a better spelling exists. Check whether the notes say anything about removal before you assume a break. The same release also disabled incremental compilation by default in CI, detected through the CI environment variable, so CI builds may get slower. That one is in Cargo’s section of the notes, and it is a behavior change.

The new features are the fun part, and you should read them last. In the Rust notes, most of the fine print sits under Compatibility Notes, but the RangeInclusive change is filed under Libraries, so read every section. The obligations are in the fine print, and the fine print is usually in the same place.