Discuss #[legacy] attribute

Author: nikomatsakis

text/0000-adjust-default-object-bounds.md

@@ -10,8 +10,12 @@ Box<Trait>` and `&'x Arc<Trait>`. The existing algorithm would default
 to `&'x Box<Trait+'x>`. The proposed change is to default to `&'x
 Box<Trait+'static>`.
 
-Note: This is a **BREAKING CHANGE**. The change has [been implemented][branch]
-and its impact has been evaluated. It was
+Adds a `#[legacy(default_object_bounds)]` annotation that can be used
+to preserve the current behavior. This annotation is intended to allow
+for opt-out as described in [RFC 1122].
+
+Note: This is a **BREAKING CHANGE**. The change has
+[been implemented][branch] and its impact has been evaluated. It was
 [found to cause no root regressions][crater] on `crates.io`.
 
 # Motivation
@@ -98,6 +102,23 @@ defaults can be actively harmful, and hence force you to specify
 explicit lifetimes, whereas the newer defaults do something
 reasonable.
 
+### Opting out
+
+Even though the current defaults are judged to be suboptimal, some
+code out there may be relying on them. To make it easier to transition
+to Rust 1.1, we therefore add the option to "revert" to the older
+defaults by adding a `#[legacy]` attribute to the crate:
+
+```rust
+#![legacy(default_object_bounds)]
+
+mod foo;
+mod bar;
+```
+
+The `#[legacy]` attribute is designed to allow for more opt-outs in
+the future, as discussed in [RFC 1122].
+
 # Detailed design
 
 The rules for user-defined types from RFC 599 are altered as follows
@@ -123,6 +144,30 @@ The rules for user-defined types from RFC 599 are altered as follows
   required. There are no known examples of this in the standard
   library as this situation arises rarely in practice.*
 
+## Legacy annotation for opting out
+
+RFC 1122 suggested that, at times, it would be appropriate to include
+an *opt-out* provision that allows users to restore older behavior, to
+ease transition to the new rules. An opt-out provision makes it easy
+to restore a crate to working order quickly.
+
+This RFC proposes an attribute `#[legacy(...)]`. This attribute can be
+placed at any place in the tree and with any arguments -- however, if
+it is placed in an unexpected location, or with unexpected arguments,
+a lint warning (unused attribute) will be signaled. It is important
+that we never signal errors so as to allow new legacy opt-outs to be
+added in the future without causing older compilers to break
+(unfortunately, the 1.0 compiler will still reject the legacy
+annotation, but adding this change now lays the groundwork for the
+future).
+
+With regard to this specific change, the annotation
+`#![legacy(default_object_bounds)]` will be accepted at the crate
+level (and only at the crate level). It will cause the older rules to
+be applied. This legacy opt-out is not time-limited and will be
+available indefinitely (this poses very little maintenance burden in
+the compiler). Any other use will yield a lint error.
+  
 # Timing and breaking change implications
 
 This is a breaking change, and hence it behooves us to evaluate the
@@ -227,3 +272,4 @@ to contain borrowed data".
 [crater]: https://gist.github.com/brson/085d84d43c6a9a8d4dc3
 [branch]: https://github.com/nikomatsakis/rust/tree/better-object-defaults
 [previous run]: https://gist.github.com/brson/80f9b80acef2e7ab37ee
+[RFC 1122]: https://github.com/rust-lang/rfcs/pull/1122