Document the unique requirements for upgrading more

prominently. Unlike in the past (dating back to the 4.x branch point),
you cannot upgrade from any point on the past couple of stable
branches to -current. Due to a bug in clang that existed before
r286035 in stable/9 or r286033 in stable/10, we cannot compile llvm
that's in 11.x or -current. Unfortunately, these revisions are after
9.3R and 10.3R on their respective branches. stable/11 and 11.0R are
not affected.

This also affects the upgrade path to 11 (including 11.0R) from
stable/9 and stable/10 (which would otherwise work, were it not for
this bug).

We also need to amend the 11.0R release notes.

MFC After: 3 days

1 files changed, 26 insertions, 6 deletions

diff --git a/UPDATING b/UPDATING
index a744cb841b68..169f7f180dac 100644
--- a/UPDATING
+++ b/UPDATING
@@ -29,7 +29,23 @@ NOTE TO PEOPLE WHO THINK THAT FreeBSD 12.x IS SLOW:
 	machines to maximize performance.  (To completely disable malloc
 	debugging, define MALLOC_PRODUCTION in /etc/make.conf, or to merely
 	disable the most expensive debugging functionality run
-	"ln -s 'abort:false,junk:false' /etc/malloc.conf".)
+	"ln -s 'abort:false,junk:false' /etc/malloc.
+
+
+****************************** SPECIAL WARNING: ******************************
+
+	Due to a bug in some versions of clang that's very hard to workaround in
+	the upgrade process, to upgrade to -current you must first upgrade
+	either stable/9 after r286035 or stable/10 after r286033 or current
+	after r286007 (including stable/11 and 11.0-RELEASE). These revisions
+	post-date 10.3-RELEASE and 9.3-RELEASE, so you'll need to take the
+	unusual step of upgrading to the tip of the stable branch before moving
+	to 11 or -current via a source upgrade.  stable/11 and 11.0-RELEASE
+	post-date the fix so you can move from them to -current. This differs
+	from the historical situation where one coule upgrade from anywhere on
+	the last couple of stable branches, so be careful.
+
+****************************** SPECIAL WARNING: ******************************
 
 20161017:
 	The urtwn(4) driver was merged into rtwn(4) and now consists of
@@ -1467,11 +1483,15 @@ COMMON ITEMS:
 	your build attempts in an "environmental clean room", prefix all make
 	commands with 'env -i '.  See the env(1) manual page for more details.
 
-	When upgrading from one major version to another it is generally best
-	to upgrade to the latest code in the currently installed branch first,
-	then do an upgrade to the new branch. This is the best-tested upgrade
-	path, and has the highest probability of being successful.  Please try
-	this approach before reporting problems with a major version upgrade.
+	When upgrading from one major version to another it is generally best to
+	upgrade to the latest code in the currently installed branch first, then
+	do an upgrade to the new branch. This is the best-tested upgrade path,
+	and has the highest probability of being successful.  Please try this
+	approach if you encounter problems with a major version upgrade.  Since
+	the stable 4.x branch point, one has generally been able to upgade from
+	anywhere in the most recent stable branch to head / current (or even the
+	last couple of stable branches). See the top of this file when there's
+	an exception.
 
 	When upgrading a live system, having a root shell around before
 	installing anything can help undo problems. Not having a root shell