-Yscala-release support: test cats-effect compiled with scala 3.0.2 while the dependencies are compiled with -Yscala-release 3.0; improve documentation

Author: prolativ

community-build/src/scala/dotty/communitybuild/projects.scala

@@ -517,7 +517,7 @@ object projects:
     dependencies   = () => List(cats, coop, disciplineSpecs2, scalacheck)
   )
 
-  lazy val catsEffect3ForwardCompat = catsEffect3.forwardCompat.withScalaRelease("3.0")
+  lazy val catsEffect3ForwardCompat = catsEffect3.forwardCompat.copy(compilerVersion = "3.0.2")
 
   lazy val scalaParallelCollections = SbtCommunityProject(
     project        = "scala-parallel-collections",

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -310,7 +310,7 @@ private sealed trait YSettings:
   val YexplicitNulls: Setting[Boolean] = BooleanSetting("-Yexplicit-nulls", "Make reference types non-nullable. Nullable types can be expressed with unions: e.g. String|Null.")
   val YcheckInit: Setting[Boolean] = BooleanSetting("-Ysafe-init", "Ensure safe initialization of objects")
   val YrequireTargetName: Setting[Boolean] = BooleanSetting("-Yrequire-targetName", "Warn if an operator is defined without a @targetName annotation")
-  val YscalaRelease: Setting[String] = ChoiceSetting("-Yscala-release", "release", "Emit TASTy files that can be consumed by specified version of the compiler.", ScalaSettings.supportedScalaReleaseVersions, "", aliases = List("--Yscala-release"))
+  val YscalaRelease: Setting[String] = ChoiceSetting("-Yscala-release", "release", "Emit TASTy files that can be consumed by specified version of the compiler. The compilation will fail if for any reason valid TASTy cannot be produced (e.g. the code contains references to some parts of the standard library API that are missing in the older stdlib or uses language features unexpressible in the older version of TASTy format)", ScalaSettings.supportedScalaReleaseVersions, "", aliases = List("--Yscala-release"))
 
   /** Area-specific debug output */
   val YexplainLowlevel: Setting[Boolean] = BooleanSetting("-Yexplain-lowlevel", "When explaining type errors, show types at a lower level.")

docs/docs/contributing/testing.md

@@ -127,6 +127,17 @@ $ sbt
 > testCompilation --help
 ```
 
+### Joint and separate sources compilation
+
+When the sources of a test consist of multiple source files places in a single directory they are passed to the compiler in a single run and the compiler decides in which order to compile them. In some cases, however, to reproduce a specific test scenario it might be necessary to compile the source files in several steps in a specified order. To achieve that one can add a `_${step_index}` suffix to a file name (before the `.scala` or `.java` extension) indicating the order of compilation. E.g. if the test directory contains files named `Foo_1.scala`, `Bar_2.scala` and `Baz_2.scala` then `Foo_1.scala` will be compiled first and after that `Bar_2.scala` together with `Baz_2.scala`.
+
+There are also other suffixes indicating how some particular files are compiled:
+* `_c${compilerVersion}` - compile a file with a specific version of the compiler instead of the one developed on the current branch
+  (e.g. `Foo_c3.0.2.scala`)
+* `_r${release}` - compile a file with a given value of `-Yscala-release` flag (e.g. `Foo_r3.0.scala`)
+
+Different suffixes can be mixed together (their order is not important although consistency is advised), e.g. `Foo_1_r3.0`, `Bar_2_c3.0.2`.
+
 ### Bootstrapped-only tests
 
 To run `testCompilation` on a bootstrapped Dotty compiler, use

sbt-community-build/src/dotty/communitybuild/sbtplugin/CommunityBuildPlugin.scala

@@ -50,8 +50,12 @@ object CommunityBuildPlugin extends AutoPlugin {
   override val buildSettings: Seq[Setting[_]] = Seq(
     dependencyOverrides ++= {
       if (scalaVersion.value.startsWith("3.")) {
-        val predicate: ModuleID => Boolean = if (isForwardCompatProject.value) (_.revision.contains("-forward-compat")) else (!_.revision.contains("-forward-compat"))
-        CommunityBuildDependencies.allOverrides(sLog.value).filter(predicate)
+        val forwardCompatFilter: ModuleID => Boolean = if (isForwardCompatProject.value) (_.revision.contains("-forward-compat")) else (!_.revision.contains("-forward-compat"))
+        val stdlibOverrides = Seq(
+          scalaOrganization.value %% "scala3-library" % scalaVersion.value,
+          scalaOrganization.value %% "scala3-library_sjs1" % scalaVersion.value,
+        )
+        CommunityBuildDependencies.allOverrides(sLog.value).filter(forwardCompatFilter) ++ stdlibOverrides
       } else Nil
     }
   )