Add FAQ for NLL migration

src/librustc_mir/borrow_check/mod.rs

@@ -439,10 +439,11 @@ fn downgrade_if_error(diag: &mut Diagnostic) {
         diag.warn(
             "this error has been downgraded to a warning for backwards \
             compatibility with previous releases",
-        );
-        diag.warn(
+        ).warn(
             "this represents potential undefined behavior in your code and \
             this warning will become a hard error in the future",
+        ).note(
+            "for more information, try `rustc --explain E0729`"
         );
     }
 }

src/librustc_mir/error_codes.rs

@@ -2424,6 +2424,38 @@ const fn foo() -> impl T {
 ```
 "##,
 
+E0729: r##"
+Support for Non-Lexical Lifetimes (NLL) has been included in the Rust compiler
+since 1.31, and has been enabled on the 2015 edition since 1.36. The new borrow
+checker for NLL uncovered some bugs in the old borrow checker, which in some
+cases allowed unsound code to compile, resulting in memory safety issues.
+
+### What do I do?
+
+Change your code so the warning does no longer trigger. For backwards
+compatibility, this unsound code may still compile (with a warning) right now.
+However, at some point in the future, the compiler will no longer accept this
+code and will throw a hard error.
+
+### Shouldn't you fix the old borrow checker?
+
+The old borrow checker has known soundness issues that are basically impossible
+to fix. The new NLL-based borrow checker is the fix.
+
+### Can I turn these warnings into errors by denying a lint?
+
+No.
+
+### When are these warnings going to turn into errors?
+
+No formal timeline for turning the warnings into errors has been set. See
+[GitHub issue 58781](https://github.com/rust-lang/rust/issues/58781) for more
+information.
+
+### Why do I get this message with code that doesn't involve borrowing?
+
+There are some known bugs that trigger this message.
+"##,
 }
 
 register_diagnostics! {

src/test/ui/borrowck/borrowck-anon-fields-variant.stderr

@@ -12,6 +12,7 @@ LL |     *a += 1;
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error[E0503]: cannot use `y` because it was mutably borrowed
   --> $DIR/borrowck-anon-fields-variant.rs:37:7

src/test/ui/borrowck/borrowck-describe-lvalue.stderr

@@ -341,6 +341,7 @@ LL |             drop(x);
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 warning[E0502]: cannot borrow `*block.current` as immutable because it is also borrowed as mutable
   --> $DIR/borrowck-describe-lvalue.rs:227:33
@@ -355,6 +356,7 @@ LL |             drop(x);
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error[E0382]: use of moved value: `x`
   --> $DIR/borrowck-describe-lvalue.rs:282:22

src/test/ui/borrowck/borrowck-migrate-to-nll.edition.stderr

@@ -6,4 +6,5 @@ LL |                 (|| { let bar = foo; bar.take() })();
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 

src/test/ui/borrowck/borrowck-migrate-to-nll.zflag.stderr

@@ -6,4 +6,5 @@ LL |                 (|| { let bar = foo; bar.take() })();
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 

src/test/ui/borrowck/borrowck-mutate-in-guard.stderr

@@ -28,6 +28,7 @@ LL |         Enum::A(_) if { x = Enum::B(false); false } => 1,
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 warning[E0510]: cannot mutably borrow `x` in match guard
   --> $DIR/borrowck-mutate-in-guard.rs:15:33
@@ -40,6 +41,7 @@ LL |         Enum::A(_) if { let y = &mut x; *y = Enum::B(false); false } => 1,
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to 3 previous errors
 

src/test/ui/consts/const_let_refutable.stderr

@@ -21,6 +21,7 @@ LL |     a + b
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 warning[E0381]: use of possibly uninitialized variable: `b`
   --> $DIR/const_let_refutable.rs:4:9
@@ -30,6 +31,7 @@ LL |     a + b
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to 2 previous errors
 

src/test/ui/consts/min_const_fn/min_const_fn.stderr

@@ -297,6 +297,7 @@ LL | const fn no_dyn_trait_ret() -> &'static dyn std::fmt::Debug { &() }
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error[E0723]: trait bounds other than `Sized` on const fn parameters are unstable
   --> $DIR/min_const_fn.rs:144:41

src/test/ui/consts/min_const_fn/min_const_fn_dyn.stderr

@@ -27,6 +27,7 @@ LL | const fn no_inner_dyn_trait_ret() -> Hide { Hide(HasDyn { field: &0 }) }
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to 2 previous errors
 

src/test/ui/empty/empty-never-array.stderr

@@ -19,6 +19,7 @@ LL |     u
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to previous error
 

src/test/ui/feature-gates/feature-gate-nll.stderr

@@ -11,6 +11,7 @@ LL |     m;
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: compilation successful
   --> $DIR/feature-gate-nll.rs:10:1

src/test/ui/issues/issue-15381.stderr

@@ -12,6 +12,7 @@ LL |         println!("y={}", y);
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to previous error
 

src/test/ui/issues/issue-40510-1.migrate.stderr

@@ -10,6 +10,7 @@ LL |         &mut x
    = note: ...therefore, they cannot allow references to captured variables to escape
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: compilation successful
   --> $DIR/issue-40510-1.rs:20:1

src/test/ui/issues/issue-40510-3.migrate.stderr

@@ -12,6 +12,7 @@ LL | |         }
    = note: ...therefore, they cannot allow references to captured variables to escape
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: compilation successful
   --> $DIR/issue-40510-3.rs:22:1

src/test/ui/issues/issue-45696-scribble-on-boxed-borrow.migrate.stderr

@@ -11,6 +11,7 @@ LL | }
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 warning[E0713]: borrow may still be in use when destructor runs
   --> $DIR/issue-45696-scribble-on-boxed-borrow.rs:62:5
@@ -25,6 +26,7 @@ LL | }
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 warning[E0713]: borrow may still be in use when destructor runs
   --> $DIR/issue-45696-scribble-on-boxed-borrow.rs:73:5
@@ -39,6 +41,7 @@ LL | }
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: compilation successful
   --> $DIR/issue-45696-scribble-on-boxed-borrow.rs:80:1

src/test/ui/issues/issue-49824.stderr

@@ -15,6 +15,7 @@ LL | |         }
    = note: ...therefore, they cannot allow references to captured variables to escape
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: compilation successful
   --> $DIR/issue-49824.rs:6:1

src/test/ui/pattern/pattern-bindings-after-at.stderr

@@ -18,6 +18,7 @@ LL |             **z = None;
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to previous error
 

src/test/ui/recursion/recursive-types-are-not-uninhabited.stderr

@@ -12,6 +12,7 @@ LL |     x
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error: aborting due to previous error
 

src/test/ui/thread-local-in-ctfe.stderr

@@ -20,6 +20,7 @@ LL | static C: &u32 = &A;
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error[E0625]: thread-local statics cannot be accessed at compile-time
   --> $DIR/thread-local-in-ctfe.rs:15:16
@@ -43,6 +44,7 @@ LL | const E: &u32 = &A;
    |
    = warning: this error has been downgraded to a warning for backwards compatibility with previous releases
    = warning: this represents potential undefined behavior in your code and this warning will become a hard error in the future
+   = note: for more information, try `rustc --explain E0729`
 
 error[E0625]: thread-local statics cannot be accessed at compile-time
   --> $DIR/thread-local-in-ctfe.rs:25:5