Merge pull request #2966 from lrytz/mgs3

SethTisue · web-flow · commit 604b354d1ba6 · 2024-02-27T17:57:54.000-08:00
Add page about Scala 2 `-Xsource:3` to migration guide
diff --git a/README.md b/README.md
@@ -4,11 +4,15 @@
 
 This repository contains the source for the Scala documentation website, as well as the source for "Scala Improvement Process" (SIP) documents.
 
+## Dependencies ##
+
+This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](https://jekyllrb.com/docs/installation/) for the details.
+
 ## Quickstart ##
 
 To build and view the site locally:
 
-    gem install --user-install bundler jekyll
+    bundle install
     bundle exec jekyll serve -I
 
 ([Trouble on MacOS?](https://github.com/scala/docs.scala-lang/issues/1150))
@@ -53,10 +57,6 @@ Small changes, or corrected typos will generally be pulled in right away. Large
 existing documents will be thoroughly reviewed-- please keep in mind that, generally, new documents must be very well-polished, complete, and maintained
 in order to be accepted.
 
-## Dependencies ##
-
-This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](https://jekyllrb.com/docs/installation/) for the details.
-
 ## Building & Viewing ##
 
 cd into the directory where you cloned this repository, then install the required gems with `bundle install`. This will automatically put the gems into `./vendor/bundle`.
diff --git a/_overviews/scala3-migration/external-resources.md b/_overviews/scala3-migration/external-resources.md
@@ -2,7 +2,7 @@
 title: External Resources
 type: chapter
 description: This section lists external resources about the migration to Scala 3.
-num: 28
+num: 29
 previous-page: plugin-kind-projector
 next-page:
 ---
diff --git a/_overviews/scala3-migration/incompat-contextual-abstractions.md b/_overviews/scala3-migration/incompat-contextual-abstractions.md
@@ -2,7 +2,7 @@
 title: Contextual Abstractions
 type: section
 description: This chapter details all incompatibilities caused by the redesign of contextual abstractions
-num: 18
+num: 19
 previous-page: incompat-dropped-features
 next-page: incompat-other-changes
 ---
diff --git a/_overviews/scala3-migration/incompat-dropped-features.md b/_overviews/scala3-migration/incompat-dropped-features.md
@@ -2,7 +2,7 @@
 title: Dropped Features
 type: section
 description: This chapter details all the dropped features
-num: 17
+num: 18
 previous-page: incompat-syntactic
 next-page: incompat-contextual-abstractions
 ---
diff --git a/_overviews/scala3-migration/incompat-other-changes.md b/_overviews/scala3-migration/incompat-other-changes.md
@@ -2,7 +2,7 @@
 title: Other Changed Features
 type: section
 description: This chapter details all incompatibilities caused by changed features
-num: 19
+num: 20
 previous-page: incompat-contextual-abstractions
 next-page: incompat-type-checker
 ---
diff --git a/_overviews/scala3-migration/incompat-syntactic.md b/_overviews/scala3-migration/incompat-syntactic.md
@@ -2,7 +2,7 @@
 title: Syntactic Changes
 type: section
 description: This chapter details all the incompatibilities caused by syntactic changes
-num: 16
+num: 17
 previous-page: incompatibility-table
 next-page: incompat-dropped-features
 ---
diff --git a/_overviews/scala3-migration/incompat-type-checker.md b/_overviews/scala3-migration/incompat-type-checker.md
@@ -2,7 +2,7 @@
 title: Type Checker
 type: section
 description: This chapter details the unsoundness fixes in the type checker
-num: 20
+num: 21
 previous-page: incompat-other-changes
 next-page: incompat-type-inference
 ---
diff --git a/_overviews/scala3-migration/incompat-type-inference.md b/_overviews/scala3-migration/incompat-type-inference.md
@@ -2,7 +2,7 @@
 title: Type Inference
 type: section
 description: This chapter details the incompatibilities caused by the new type inference algorithm
-num: 21
+num: 22
 previous-page: incompat-type-checker
 next-page: options-intro
 ---
diff --git a/_overviews/scala3-migration/incompatibility-table.md b/_overviews/scala3-migration/incompatibility-table.md
@@ -2,7 +2,7 @@
 title: Incompatibility Table
 type: chapter
 description: This chapter list all the known incompatibilities between Scala 2.13 and Scala 3 
-num: 15
+num: 16
 previous-page: tooling-syntax-rewriting
 next-page: incompat-syntactic
 ---
diff --git a/_overviews/scala3-migration/options-intro.md b/_overviews/scala3-migration/options-intro.md
@@ -2,7 +2,7 @@
 title: Compiler Options
 type: chapter
 description: This chapter shows the difference between Scala 2.13 and Scala 3 compiler options
-num: 22
+num: 23
 previous-page: incompat-type-inference
 next-page: options-lookup
 ---
diff --git a/_overviews/scala3-migration/options-lookup.md b/_overviews/scala3-migration/options-lookup.md
@@ -2,7 +2,7 @@
 title: Compiler Options Lookup Table
 type: section
 description: This section contains the compiler options lookup tables
-num: 23
+num: 24
 previous-page: options-intro
 next-page: options-new
 ---
diff --git a/_overviews/scala3-migration/options-new.md b/_overviews/scala3-migration/options-new.md
@@ -2,7 +2,7 @@
 title: New Compiler Options
 type: section
 description: This chapter lists all the new compiler options in Scala 3
-num: 24
+num: 25
 previous-page: options-lookup
 next-page: scaladoc-settings-compatibility
 ---
diff --git a/_overviews/scala3-migration/plugin-intro.md b/_overviews/scala3-migration/plugin-intro.md
@@ -2,7 +2,7 @@
 title: Compiler Plugins
 type: chapter
 description: This section shows how to migrate from using Scala 2 compiler plugins
-num: 26
+num: 27
 previous-page: options-new
 next-page: plugin-kind-projector
 ---
diff --git a/_overviews/scala3-migration/plugin-kind-projector.md b/_overviews/scala3-migration/plugin-kind-projector.md
@@ -2,7 +2,7 @@
 title: Kind Projector Migration
 type: section
 description: This section shows how to migrate from the kind-projector plugin to Scala 3 kind-projector syntax
-num: 27
+num: 28
 previous-page: plugin-intro
 next-page: external-resources
 ---
diff --git a/_overviews/scala3-migration/scala3-migrate.md b/_overviews/scala3-migration/scala3-migrate.md
@@ -2,7 +2,7 @@
 title: Porting an sbt Project (using sbt-scala3-migrate)
 type: section
 description: This section shows how to use scala3-migrate to migrate a project
-num: 10
+num: 11
 previous-page: tutorial-prerequisites
 next-page: tutorial-sbt
 ---
@@ -17,12 +17,13 @@ It consists of four sbt commands:
 Each one of these commands is described in details below.
 
 > #### Requirements
-> - Scala 2.13, preferred 2.13.11
+> - Scala 2.13, preferred 2.13.13
 > - sbt 1.5 or higher
 > - **Disclaimer:** This tool cannot migrate libraries containing macros.
 >
 > #### Recommendation
-> Before the migration, add `-Xsource:3` to your scalac options to enable some Scala 3 syntax and behavior.
+> Before the migration, add `-Xsource:3` to your scalac options to enable Scala 3 migration warnings in the Scala 2 compiler.
+> See the page [Scala 2 with -Xsource:3](tooling-scala2-xsource3.html) for more details.
 
 In this tutorial, we will migrate the project in [scalacenter/scala3-migration-example](https://github.com/scalacenter/scala3-migration-example).
 To learn about the migration, and train yourself, you can clone this repository and follow the tutorial steps.
diff --git a/_overviews/scala3-migration/scaladoc-settings-compatibility.md b/_overviews/scala3-migration/scaladoc-settings-compatibility.md
@@ -2,7 +2,7 @@
 title: Scaladoc settings compatibility between Scala2 and Scala3
 type: section
 description: This chapter lists all the scaladoc options for Scala 2 and Scala 3, and explains the relations between them.
-num: 25
+num: 26
 previous-page: options-new
 next-page: plugin-intro
 ---
diff --git a/_overviews/scala3-migration/tooling-migration-mode.md b/_overviews/scala3-migration/tooling-migration-mode.md
@@ -2,8 +2,8 @@
 title: Scala 3 Migration Mode
 type: chapter
 description: This section describes the migration mode of the Scala 3 compiler 
-num: 7
-previous-page: tooling-tour
+num: 8
+previous-page: tooling-scala2-xsource3
 next-page: tutorial-intro
 ---
 
diff --git a/_overviews/scala3-migration/tooling-scala2-xsource3.md b/_overviews/scala3-migration/tooling-scala2-xsource3.md
@@ -0,0 +1,87 @@
+---
+title: Scala 2 with -Xsource:3
+type: chapter
+description: This section describes the Scala 2 compiler's -Xsource:3 flag
+num: 7
+previous-page: tooling-tour
+next-page: tooling-migration-mode
+---
+
+The Scala 2.13 compiler issues helpful migration warnings with the `-Xsource:3` flag.
+
+Before moving to the Scala 3 compiler, it's recommended to enable this flag in Scala 2 and address the new warnings.
+
+There is also a variant, `-Xsource:3-cross`; see below.
+
+This page explains the details behind the flags. An overview is shown using `scalac -Xsource:help`.
+
+## Migration vs cross-building
+
+With Scala 2.13.13 and newer, the `-Xsource:3` flag comes in two variants:
+
+  - `Xsource:3` enables warnings relevant for migrating a codebase to Scala 3.
+    In addition to new warnings, the flag enables certain benign Scala 3 syntaxes such as `import p.*`.
+  - `Xsource:3-cross` is useful for projects that cross-build between Scala 2 and 3 for a longer period of time.
+    For certain language constructs that trigger a warning with `-Xsource:3`, the behavior changes to match Scala 3.
+
+Details about individual warnings are listed below on this page.
+
+## Fatal warnings and quick fixes
+
+By default, Scala 3 migration warnings emitted by Scala 2.13 are fatal, i.e., they are reported as errors.
+This can be changed using `-Wconf`, for example `-Wconf:cat=scala3-migration:w` changes them to be reported as warnings.
+Alternatively, `-Xmigration` has the same effect.
+
+The [`@nowarn` annotation](https://www.scala-lang.org/api/current/scala/annotation/nowarn.html) can be used to suppress individual warnings, which also works with fatal warnings enabled.
+
+The Scala 2.13 compiler implements quick fixes for many Scala 3 migration warnings.
+Quick fixes are displayed in Metals-based IDEs (not yet in IntelliJ), and they can be applied directly to the source code using the `-quickfix` flag, for example `-quickfix:cat=scala3-migration`.
+See also `scalac -quickfix:help`.
+
+## Enabled Scala 3 syntax
+
+The `-Xsource:3` flag enables the following Scala 3 syntaxes in Scala 2:
+
+  - `import p.*`
+  - `import p.m as n`
+  - `import p.{given, *}`
+  - `case C(xs*)` as an alias for `case C(xs @ _*)`
+  - `A & B` type intersection as an alias for `A with B`
+  - Selecting a method `x.f` performs an eta-expansion (`x.f _`), even without an expected type
+
+## Scala 3 migration warnings in detail
+
+Many Scala 3 migration warnings are easy to understand and identical under `-Xsource:3` and `-Xsource:3-cross`, e.g., for implicit definitions without an explicit type:
+
+{% highlight text %}
+scala> object O { implicit val s = "" }
+                               ^
+       error: Implicit definition must have explicit type (inferred String) [quickfixable]
+{% endhighlight %}
+
+The following table explains warnings where where the behavior changes between `-Xsource:3` and `-Xsource:3-cross`.
+
+| Feature | `-Xsource:3` | `-Xsource:3-cross` |
+|--- |--- |--- |
+| `(x: Any) + ""` is deprecated | deprecation warning | does not compile, implicit `any2stringadd` is not inferred |
+| Unicode escapes in triple-quoted strings and raw interpolations (`"""\u0061"""`) | fatal warning, escape is processed | escape is not processed |
+| Leading infix operators continue the previous line <sup>1</sup> | fatal warning, second line is a separate expression | operation continues the previous line |
+| Desugaring of string interpolators using `StringContext` | fatal warning if the interpolation references a `StringContext` in scope different from `scala.StringContext` | desugaring always uses `scala.StringContext` |
+| Modifiers of `apply` and `copy` methods of case classes with non-public constructors: `case class C private[p] (x: Int)` | fatal warning about the generated `apply` and `copy` being public | `apply` and `copy` inherit the access modifiers from the constructor |
+| Inferred type of an overriding member <sup>2</sup> | fatal warning, the type of `B.f` is `String` | the type of `B.f` is `Object` |
+| An implicit for type `p.A` is found in the package prefix `p` | fatal warning | the package prefix `p` is no longer part of the implicit search scope |
+
+Example 1:
+
+{% highlight text %}
+  def f =
+    1
+    + 2
+{% endhighlight %}
+
+Example 2:
+
+{% highlight text %}
+trait A { def f: Object }
+class B extends A { def f = "hi" }
+{% endhighlight %}
diff --git a/_overviews/scala3-migration/tooling-syntax-rewriting.md b/_overviews/scala3-migration/tooling-syntax-rewriting.md
@@ -2,7 +2,7 @@
 title: Scala 3 Syntax Rewriting
 type: chapter
 description: This section describes the syntax rewriting capability of the Scala 3 compiler 
-num: 14
+num: 15
 previous-page: tutorial-macro-mixing
 next-page: incompatibility-table
 ---
diff --git a/_overviews/scala3-migration/tooling-tour.md b/_overviews/scala3-migration/tooling-tour.md
@@ -4,7 +4,7 @@ type: chapter
 description: This chapter is a tour of the migration tooling ecosystem 
 num: 6
 previous-page: compatibility-metaprogramming
-next-page: tooling-migration-mode
+next-page: tooling-scala2-xsource3
 ---
 
 ## The Scala Compilers
@@ -13,12 +13,10 @@ The migration has been carefully prepared beforehand in each of the two compiler
 
 ### The Scala 2.13 Compiler
 
-The Scala 2.13 compiler supports `-Xsource:3`, an option that enables some Scala 3 syntax and behavior:
-- Most deprecated syntax generates an error.
-- Infix operators can start a line in the middle of a multiline expression.
-- Implicit search and overload resolution follow Scala 3 handling of contravariance when checking specificity.
+The Scala 2.13 compiler supports `-Xsource:3`, an option that enables migration warnings and certain Scala 3 syntax and behavior.
+
+The [Scala 2 with -Xsource:3](tooling-scala2-xsource3.html) page explains the flag in detail.
 
-The `-Xsource:3` option is intended to encourage early migration.
 
 ### The Scala 3 Compiler
 
diff --git a/_overviews/scala3-migration/tutorial-intro.md b/_overviews/scala3-migration/tutorial-intro.md
@@ -2,7 +2,7 @@
 title: Migration Tutorial
 type: chapter
 description: This chapter contains the tutorials for porting a Scala 2.13 project to Scala 3 
-num: 8
+num: 9
 previous-page: tooling-migration-mode
 next-page: tutorial-prerequisites
 ---
diff --git a/_overviews/scala3-migration/tutorial-macro-cross-building.md b/_overviews/scala3-migration/tutorial-macro-cross-building.md
@@ -2,7 +2,7 @@
 title: Cross-Building a Macro Library
 type: section
 description: This section shows how to cross-build a macro library
-num: 12
+num: 13
 previous-page: tutorial-sbt
 next-page: tutorial-macro-mixing
 ---
diff --git a/_overviews/scala3-migration/tutorial-macro-mixing.md b/_overviews/scala3-migration/tutorial-macro-mixing.md
@@ -2,7 +2,7 @@
 title: Mixing Scala 2.13 and Scala 3 Macros
 type: section
 description: This section shows how to mix Scala 2.13 and Scala 3 macros in a single artifact
-num: 13
+num: 14
 previous-page: tutorial-macro-mixing
 next-page: tooling-syntax-rewriting
 ---
diff --git a/_overviews/scala3-migration/tutorial-prerequisites.md b/_overviews/scala3-migration/tutorial-prerequisites.md
@@ -2,7 +2,7 @@
 title: Prerequisites
 type: section
 description: This section details the prerequisites of migration to Scala 3
-num: 9
+num: 10
 previous-page: tutorial-intro
 next-page: scala3-migrate
 ---
diff --git a/_overviews/scala3-migration/tutorial-sbt.md b/_overviews/scala3-migration/tutorial-sbt.md
@@ -2,7 +2,7 @@
 title: Porting an sbt Project (by hand)
 type: section
 description: This section shows how to port an sbt project
-num: 11
+num: 12
 previous-page: scala3-migrate
 next-page: tutorial-macro-cross-building
 ---
