From bfbd5e05c7b8daa7621d809038c53781ab99736c Mon Sep 17 00:00:00 2001
From: Jamie Thompson <bishbashboshjt@gmail.com>
Date: Thu, 2 Nov 2023 16:41:35 +0100
Subject: [PATCH] add url to scala docs for tasty versioning

---
 .../tools/tasty/TastyHeaderUnpickler.scala    |  8 ++-
 .../tasty/TastyHeaderUnpicklerTest.scala      | 60 ++++++++++++++-----
 2 files changed, 51 insertions(+), 17 deletions(-)

diff --git a/tasty/src/dotty/tools/tasty/TastyHeaderUnpickler.scala b/tasty/src/dotty/tools/tasty/TastyHeaderUnpickler.scala
index 0a7f67d4da96..ecfbda54d847 100644
--- a/tasty/src/dotty/tools/tasty/TastyHeaderUnpickler.scala
+++ b/tasty/src/dotty/tools/tasty/TastyHeaderUnpickler.scala
@@ -137,7 +137,7 @@ class TastyHeaderUnpickler(config: UnpicklerConfig, reader: TastyReader) {
       val toolVersion = TastyVersion(toolMajor, toolMinor, toolExperimental)
       val signature = signatureString(fileVersion, toolVersion, what = "backward", tool = None)
       val fix = recompileFix(toolVersion.minStable)
-      throw new UnpickleException(signature + fix)
+      throw new UnpickleException(signature + fix + tastyAddendum)
     }
     else {
       val fileMinor = readNat()
@@ -185,7 +185,7 @@ class TastyHeaderUnpickler(config: UnpicklerConfig, reader: TastyReader) {
           }
           else upgradeFix(fileVersion)
         )
-        signature + fix
+        signature + fix + tastyAddendum
       })
 
       val uuid = new UUID(readUncompressedLong(), readUncompressedLong())
@@ -218,6 +218,10 @@ class TastyHeaderUnpickler(config: UnpicklerConfig, reader: TastyReader) {
     val newTool = config.upgradedReaderTool(fileVersion)
     s"""  To read this ${fileVersion.kind} file, use $newTool.$addendum""".stripMargin
   }
+
+  private def tastyAddendum: String = """
+  |  Please refer to the documentation for information on TASTy versioning:
+  |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
 }
 
 object TastyHeaderUnpickler {
diff --git a/tasty/test/dotty/tools/tasty/TastyHeaderUnpicklerTest.scala b/tasty/test/dotty/tools/tasty/TastyHeaderUnpicklerTest.scala
index 785ae9de297d..58805ce27aee 100644
--- a/tasty/test/dotty/tools/tasty/TastyHeaderUnpicklerTest.scala
+++ b/tasty/test/dotty/tools/tasty/TastyHeaderUnpicklerTest.scala
@@ -54,7 +54,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 3.4.0-RC1-bin-SNAPSHOT has a backward incompatible TASTy version 28.4-experimental-1,
         |  expected stable TASTy from 28.0 to 28.4.
         |  The source of this file should be recompiled by a Scala 3.4.0 compiler or newer.
-        |  Usually this means that the library dependency containing this file should be updated.""".stripMargin
+        |  Usually this means that the library dependency containing this file should be updated.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -66,7 +68,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 3.2.1-RC1-bin-SNAPSHOT has a backward incompatible TASTy version 28.3-experimental-1,
         |  expected stable TASTy from 28.0 to 28.4.
         |  The source of this file should be recompiled by a Scala 3.3.0 compiler or newer.
-        |  Usually this means that the library dependency containing this file should be updated.""".stripMargin
+        |  Usually this means that the library dependency containing this file should be updated.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -78,7 +82,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file has a backward incompatible TASTy version 27.3,
         |  expected stable TASTy from 28.0 to 28.3.
         |  The source of this file should be recompiled by a Scala 3.0.0 compiler or newer.
-        |  Usually this means that the library dependency containing this file should be updated.""".stripMargin
+        |  Usually this means that the library dependency containing this file should be updated.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -91,7 +97,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file has a backward incompatible TASTy version 27.3,
         |  expected stable TASTy from 28.0 to 28.3.
         |  The source of this file should be recompiled by a later version.
-        |  Usually this means that the classpath entry of this file should be updated.""".stripMargin
+        |  Usually this means that the classpath entry of this file should be updated.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -103,7 +111,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 3.3.3-RC1-NIGHTLY has a backward incompatible TASTy version 28.4-experimental-1,
         |  expected stable TASTy from 28.0 to 28.3, or exactly 28.4-experimental-2.
         |  The source of this file should be recompiled by the same nightly or snapshot Scala 3.3 compiler.
-        |  Usually this means that the library dependency containing this file should be updated.""".stripMargin
+        |  Usually this means that the library dependency containing this file should be updated.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -116,7 +126,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 3.3.3-RC1-NIGHTLY has a backward incompatible TASTy version 28.4-experimental-1,
         |  expected stable TASTy from 28.0 to 28.3, or exactly 28.4-experimental-2.
         |  The source of this file should be recompiled by a later version.
-        |  Usually this means that the classpath entry of this file should be updated.""".stripMargin
+        |  Usually this means that the classpath entry of this file should be updated.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -127,7 +139,9 @@ class TastyHeaderUnpicklerTest {
     expectUnpickleError(runTest(file, read, "Scala 3.3.1")) {
       """TASTy file produced by Scala 3.3.1 has a forward incompatible TASTy version 28.3,
         |  expected stable TASTy from 28.0 to 28.2.
-        |  To read this TASTy file, use a Scala 3.3.0 compiler or newer.""".stripMargin
+        |  To read this TASTy file, use a Scala 3.3.0 compiler or newer.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -139,7 +153,9 @@ class TastyHeaderUnpicklerTest {
     expectUnpickleError(runTest(file, read, "Scala 3.3.1", generic = true)) {
       """TASTy file produced by Scala 3.3.1 has a forward incompatible TASTy version 28.3,
         |  expected stable TASTy from 28.0 to 28.2.
-        |  To read this TASTy file, use a newer version of this tool compatible with TASTy 28.3.""".stripMargin
+        |  To read this TASTy file, use a newer version of this tool compatible with TASTy 28.3.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -151,7 +167,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 3.2.2-RC1-NIGHTLY has a forward incompatible TASTy version 28.3-experimental-1,
         |  expected stable TASTy from 28.0 to 28.2.
         |  To read this experimental TASTy file, use the same nightly or snapshot Scala 3.2 compiler.
-        |  Note that you are using a stable compiler, which can not read experimental TASTy.""".stripMargin
+        |  Note that you are using a stable compiler, which can not read experimental TASTy.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -162,7 +180,9 @@ class TastyHeaderUnpicklerTest {
     expectUnpickleError(runTest(file, read, "Scala 4.0.0")) {
       """TASTy file produced by Scala 4.0.0 has a forward incompatible TASTy version 29.0,
         |  expected stable TASTy from 28.0 to 28.3.
-        |  To read this TASTy file, use a more recent Scala compiler.""".stripMargin
+        |  To read this TASTy file, use a more recent Scala compiler.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -174,7 +194,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 4.0.0-M1 has a forward incompatible TASTy version 29.0-experimental-1,
         |  expected stable TASTy from 28.0 to 28.3.
         |  To read this experimental TASTy file, use the same Scala compiler.
-        |  Note that you are using a stable compiler, which can not read experimental TASTy.""".stripMargin
+        |  Note that you are using a stable compiler, which can not read experimental TASTy.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -187,7 +209,9 @@ class TastyHeaderUnpicklerTest {
       """TASTy file produced by Scala 4.0.0-M1 has a forward incompatible TASTy version 29.0-experimental-1,
         |  expected stable TASTy from 28.0 to 28.3.
         |  To read this experimental TASTy file, use the version of this tool compatible with TASTy 29.0-experimental-1.
-        |  Note that this tool does not support reading experimental TASTy.""".stripMargin
+        |  Note that this tool does not support reading experimental TASTy.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -198,7 +222,9 @@ class TastyHeaderUnpicklerTest {
     expectUnpickleError(runTest(file, read, "Scala 3.4.2")) {
       """TASTy file produced by Scala 3.4.2 has a forward incompatible TASTy version 28.4,
         |  expected stable TASTy from 28.0 to 28.3, or exactly 28.4-experimental-1.
-        |  To read this TASTy file, use a Scala 3.4.0 compiler or newer.""".stripMargin
+        |  To read this TASTy file, use a Scala 3.4.0 compiler or newer.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -209,7 +235,9 @@ class TastyHeaderUnpicklerTest {
     expectUnpickleError(runTest(file, read, "Scala 3.3.3-RC2-NIGHTLY")) {
       """TASTy file produced by Scala 3.3.3-RC2-NIGHTLY has a forward incompatible TASTy version 28.4-experimental-2,
         |  expected stable TASTy from 28.0 to 28.3, or exactly 28.4-experimental-1.
-        |  To read this experimental TASTy file, use the same nightly or snapshot Scala 3.3 compiler.""".stripMargin
+        |  To read this experimental TASTy file, use the same nightly or snapshot Scala 3.3 compiler.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }
 
@@ -221,7 +249,9 @@ class TastyHeaderUnpicklerTest {
     expectUnpickleError(runTest(file, read, "Scala 3.3.3-RC2-NIGHTLY", generic = true)) {
       """TASTy file produced by Scala 3.3.3-RC2-NIGHTLY has a forward incompatible TASTy version 28.4-experimental-2,
         |  expected stable TASTy from 28.0 to 28.3, or exactly 28.4-experimental-1.
-        |  To read this experimental TASTy file, use the version of this tool compatible with TASTy 28.4-experimental-2.""".stripMargin
+        |  To read this experimental TASTy file, use the version of this tool compatible with TASTy 28.4-experimental-2.
+        |  Please refer to the documentation for information on TASTy versioning:
+        |  https://docs.scala-lang.org/scala3/reference/language-versions/binary-compatibility.html""".stripMargin
     }
   }