Add information about breaking changes when adding types to the prelude

Author: joshtriplett

src/breaking-changes/prelude.md

@@ -1,7 +1,7 @@
 # Breaking changes to the prelude
 
 Making changes to the prelude can easily cause breakage because it impacts all Rust code.
-In most cases the impact is limited since prelude items have the lowest priority in name lookup (lower than glob imports), but there are two cases where this doesn't work.
+In most cases the impact is limited since prelude items have the lowest priority in name lookup (lower than glob imports), but there are three cases where this requires additional care or may not be possible.
 
 ## Traits
 
@@ -16,3 +16,13 @@ Unlike other item types, rustc's name resolution for macros does not support giv
 As a general rule, avoid adding macros to the prelude except at edition boundaries.
 
 This issues was encoutered when trying to land the [`assert_matches!` macro](https://github.com/rust-lang/rust/issues/82913).
+
+## Types
+
+Adding a new type usually doesn't create any breakage, because prelude types have a lower priority than names in user code.
+
+However, code that declares an enum, *and* has a derive on that enum, *and* attempts to locally import a variant from that enum (e.g. `use EnumType::Variant;`) will break if the prelude starts exporting a type with the same name as that enum.
+
+This makes adding a new type to the prelude require a crater run to check for breakage in existing Rust code.
+
+If Rust code declares a local variable binding and the prelude adds a type of the same name, this can likewise introduce breakage. This case is much less likely to arise, as it requires declaring a variable name using the `CamelCase` convention typically used for types, and ignoring rustc's warnings about doing so.

src/policy/prelude.md

@@ -18,20 +18,33 @@ prelude for all Rust editions.
 When to use editions
 --------------------
 
+[Some kinds of additions to the prelude can cause breakage in existing
+code](../breaking-changes/prelude.md), so we must either avoid making such
+changes entirely or check carefully with crater before making them.
+
 Adding a trait to the prelude can break existing Rust code, by creating name
 resolution ambiguity where none previously existed. While introducing
 resolution ambiguities may be "permitted breakage", doing so is quite
 disruptive, and we want to avoid doing so. Thus, we generally never add a trait
-to the common prelude; we only add traits to the prelude for a new edition of
+to the common prelude; we only add traits to the preludes for new editions of
 Rust.
 
-Adding items *other* than traits to the prelude will never produce conflicts or
-other compatibility issues with existing code, since we allow shadowing and
-give other sources of names priority over names from the prelude. Thus, if we
-choose to add a non-trait item to the prelude, we should typically add it to
-the common prelude for all editions of Rust. (Exceptions to this would include
-names that form part of an edition transition, such that the same name resolves
-to something different in different editions.)
+Likewise, adding a macro to the prelude can break existing code, so we
+generally can't add macros to the common prelude, and can only add macros to
+the preludes for new editions of Rust.
+
+Finally, in some cases adding a type to the prelude can break existing code.
+The cases in which this arises are narrower, but still require at a minimum
+checking a crater run.
+
+Adding items other than traits, macros, or types to the prelude will never
+produce conflicts or other compatibility issues with existing code, since we
+allow shadowing and give other sources of names priority over names from the
+prelude. Thus, if we choose to add another kind of item to the prelude, we
+should typically add it to the common prelude for all editions of Rust.
+(Exceptions to this would include names that form part of an edition
+transition, such that the same name resolves to something different in
+different editions.)
 
 Criteria for including an item
 ------------------------------