scalacenter / scala-3-migration-guide

The Scala 3 migration guide for everyone.

Scala 3 migration guide

The content of the Scala 3 migration guide has moved to docs.scala-lang.org

This repository is a continuously evolving guide to support the migration to Scala 3. As a member of the community you are encouraged to participate the effort by sharing your migrating experience.

Visit the Scala 3 Migration website to learn more about the migration.

A number of complementary initiatives are being undertaken to ease the migration. This repository is not a replacement of those initiatives. Its purpose is to gather knowledge, to collect feedback and to encourage the collaboration. The ultimate goal being to drive the effort of the community toward the release of Scala 3.0.0.

All information you may want to know before starting the migration of your codebase should be available in this guide. If not you may want to contribute.

Content

This repository contains:

• incompat-30/: A corpus of incompatibilities between Scala 2.13 and Scala 3.0 with proposed solution. It also contains the tests of the Scala 3.0 migration rewrites for 3.0.
• incompat-31/: The tests of the Dotty migration rewrites that are already implemented for 3.1.
• docs/: The documentation that is still published to the deprecated website
• website/: The website skeleton powered by Docusaurus.

Additional Resources

• The Scala website
• The Dotty website
• The Scala 3 example project
• The Scala 3 community projects
• The Scala 3 Migration Plugin for sbt

scala-3-migration-guide's Issues

Unclosed string literal in Early Initializer example

While trying out the early intializer example, it seems there is an unclosed string literal at this line because I could not get the code to compile.

Also, earlier in the example we are taking about trait Bar, so for the class example it would be helpful if the class Fizz extends Bar. Then the complete example can be compiled.

trait Bar {
  val name: String
  val size: Int = name.size
}

class Fizz private (val name: String) extends Bar {
  def this() = this("Fizz")
}

I can send a PR for this.

Since master has become main, edit button leads to "page not found"

The edit button in the documentation. e.g. at https://scalacenter.github.io/scala-3-migration-guide/docs/scala-3-syntax-rewriting.html, navigates to the URL:
https://github.com/scalacenter/scala-3-migration-guide/edit/master/docs/scala-3-syntax-rewrites.md
but it needs to go to:
https://github.com/scalacenter/scala-3-migration-guide/edit/main/docs/scala-3-syntax-rewrites.md
Workaround: simply change master to main in the URL

add note about disabling doc generation

The SBT setup page should include a note somewhere about disabling doc generation for Scala 3 because it doesn't quite work and it will hit 100% of library authors trying to publish.

  Compile / doc / sources := {
    val old = (Compile / doc / sources).value
    if (isDotty.value)
      Seq()
    else
      old
  }

Maven based projects migration guide

Would be nice to support maven based part of community. It's a thing, especially in corporate environments

Document alternatives to macro annotations

Scala 3 won't support macro annotation, which will break a number of open-source libraries.

AFAIK there is no "official" documented alternative and the only solution currently being tested by the community is to generate code using Scalafix (see simulacrum-scalafix).

The migration guide should offer alternatives to macro annotations.

Add page on compiler options

When migrating a Scala 2 project, it is useful to configure the compiler properly. The compiler pages will be dedicated to this matter.

It will contain a table of all Scala 2 compiler options, their Scala 3 equivalence, NA if missing and all other Scala 3 options.
Each row could be commented if relevant:

• reason why it is removed
• related discussions, issue or PR
• links to other pages of the guide (dotty migration mode, syntax rewrites...)

It can also include a short paragraph to show how to set the compiler options in sbt based on the scala version.

Add ambiguous reference incompatibility

Found in https://github.com/47degrees/fetch

abstract class Document {
  def ::(hd: Document): Document  = DocCons(hd, this)
  
  def foo(bar: List[String]): String = bar match {
    case head :: tail => head
  }
}

Describe technique for providing Scala 2 and Scala 3 macros in the same artifact

Describe the technique in the metaprogramming guide.

Attempting to find a place to submit an issue ticket was non-trivial...

I don't have the time (and for most others, the motivation) to try and figure these out as it would cause me to lose my current focus (evaluating a project migration LOE [Level Of Effort]) for which I came to this site in the first place.

Per item 4 in this closed ticket, please improve (or make more obvious) the link to use when "Giving feedback for missing content". From now until at least a year after the release of Scala 3, the link needs to be quite a bit more obvious to a time-pressed Scala software engineer who cannot find his/her current Scala2 to Scala3 conversion showstopper.

This is an essential bottleneck we want to expand as much as possible so it better facilitates and then accelerates the conversions to Scala3.

Move scalafix ParensAroundLambda rule to scala-rewrites repo

Validate the following rule by testing it extensively. Then move it to the scala-rewrites repository:

• fix.scala213.ParensAroundLambda rule of ohze/scala-rewrites

The incompatibility description should be updated accordingly.

Update list of migrated Scala 2 macros

At https://github.com/scalacenter/scala-3-migration-guide/blame/master/docs/macros.md#L11.

New incompatibility: case class companions don’t extend Function anymore

In Scala 2, a case class companion was extending Function.

case class Foo(x: Int, b: Boolean)

// The Scala 2 compiler synthesizes the following companion
object Foo extends Function2[Int, Boolean, Foo] {
  def apply(x: Int, b: Boolean) = new Foo(x, b)
}

This is not the case anymore, which means that companions don’t inherit function methods such as apply, tupled, andThen, and compose.

One work-around to write code that cross-compiles is to manually write a function that calls the constructor:

val fooConstructor: (Int, Boolean) => Foo = (x, b) => Foo(x, b)
// Then, `fooConstructor` has all the methods of Function

`private val` in a class might not generate a field which can break reflection

This is a breaking change mentioned in scala/scala3#13822 but which is worth highlighting in the migration guide I think (it can also affect usage of WeakReference in some situations but that's likely to be much more rare: scala/scala3#13770)

Document the dotty rewrite rules

The idea is to list and explain, with example codes, the dotc rewrite rules, and to fill this document:
https://github.com/scalacenter/scala-3-migration-guide/blob/master/docs/dotty-rewrites.md

Quoting @smarter

If you want to find all the rewrites you can grep for "patch(" in https://github.com/lampepfl/dotty/tree/master/compiler

Rename Dotty to Scala 3

See https://dotty.epfl.ch/blog/2020/09/21/naming-schema-change.html

Migrate Dotty doc scala2-vs-scala3.md

As a continuation to lampepfl/dotty-knowledge#4

Compare merge and migrate to the migration guide:

• https://github.com/lampepfl/dotty/wiki/Known-incompatibilities-with-scalac
• https://github.com/lampepfl/dotty/blob/master/docs/docs/contributing/scala2-vs-scala3.md
• scala/scala-dev#374

Add a step by step cross-compiling tutorial with sbt

Explain how to cross compile a library using sbt, in https://github.com/scalacenter/scala-3-migration-guide/blob/master/docs/cross-build.md#how-to-cross-build-your-library-with-dotty

Add link to the scala3-macros-tutorial

In the Migrating Macros page, add links towards the scala3-macros-tutorial.

Include sirthias/borer in list of macro libraries status

For tracking status of https://github.com/sirthias/borer under Macro Libraries

Rewrite options combinations

Scala 3 Syntax Rewriting shows these combinations of options.

    -indent -old-syntax -rewrite
    -no-indent -old-syntax -rewrite
    -indent -new-syntax -rewrite
    -noindent -new-syntax -rewrite

however the indent and syntax flags seem to be mutually exclusive. In my case I use before -new-syntax -rewrite and then -indent -rewrite.
Using the two at the same time (-indent -new-syntax -rewrite) produces

[error]   |illegal combination of -rewrite targets: -new-syntax and -indent

syntax rewrites page contradicts indentation documenation

I followed the https://scalacenter.github.io/scala-3-migration-guide/docs/tooling/scala-3-syntax-rewrites.html in order to rewrite a scala 2 application to scala 3.

During the migration, an error occured as documented here: scala/scala3#12503
In the discussion of this issue it was suggested to open a ticket in the migration guide, which I am now doing.

Should I repost the contents of the dotty ticket here?
The gist of it is: I performed the rewrite as documented in the migration guide: First the -rewrite -indent, then the -rewrite -new-syntax.
That results in the compilation error as discussed in the dotty issue.

The correct approach as documented here https://dotty.epfl.ch/docs/reference/other-new-features/indentation.html suggests that the operation must be done in the opposite order.

Scala 2 overrides a return type to an inferred type; Scala 3 does not

scala 2.13.5> class C; class D extends C
scala 2.13.5> class Test { def foo: C = new C }
scala 2.13.5> class Test2 extends Test { override def foo = new D }
scala 2.13.5> (new Test2).foo
val res0: D = D@5d32c1c7

whereas in Scala 3 the type of res0 is C

I'm fairly sure this is intended behavior in Scala 3, but I can't seem to find either a ticket, or a migration guide entry about it.

There is a ticket complaining about the Scala 2 behavior: scala/bug#7212

Broken link to Compatibility Reference on front page

the link (https://scalacenter.github.io/scala-3-migration-guide/docs/general/compatibility.html) is 404

Migrating Scala 2 compiler plugins

Doc: http://dotty.epfl.ch/docs/reference/changed-features/compiler-plugins.html

Add a FAQ page

Add a FAQ page to answer the most frequently asked questions.

"Migrating Macros" links broken on start page

At the bottom of https://scalacenter.github.io/scala-3-migration-guide, the two "Migrating Macros" links are broken

Document Tasty Reader compatible features

List all the compatible Scala 3 features

• give an example
• what are the limitations

List all the incompatible Scala 3 features

Import * now means wildcard

There is probably a creative example where someone previously only wanted to import a * operation and now they import every operation, and importing everything now shadows some other definition.

class Operations {
  def *(i: Int, j: Int) = i * j
  def println(any: Any): Unit = ???
}

object Main extends App {
  val ops = new Operations()
  import ops.*
  println(*(2, 3))
}

Edit: on Scala 3 running Main will eval ??? in Operations.println, but Scala 2.13 will use Predef.println and print 6

Initiate the tutorial for migrating an sbt project

The tutorial covers the following steps

• Prerequisite: scala version >2.13, valid compiler plugins, no macro annotations...
• Find the right set of dependencies: most scala 2 dependencies are compatible with scala 3. For the macro libraries it is required to upgrade to a cross-compiled version.
• Optionally fix some incompatibilities with Scalafix (link to the scalafix tutorial #62)
• Configure the build tool for cross compilation: use sbt 1.4.0-RC2, sbt-dotty plugin and the crossVersions settings
• Find the right set of dotc options depending on the scalac options (link to the compiler options page #60)
• Add the dotc migration mode options
• Try to compile with Dotty / fix the errors / compile in 2.13 / run the tests in 2.13 / iterate
• Rewrite with Dotty if necessary
• Leave the Dotty migration mode

Add Scalafix tutorial for migration (sbt)

Add a specific page to explain how to use Scalafix during the migration.
This page will be first based on sbt.

Broken links in README.md

Sorry pls, but after the text: "This repository contains:" most links in the list are broken.

Add Monocle to the list of macro libraries

Monocle is missing from the list of macro libraries. By the looks of things it has been migrated to Scala 3.

Document editors (metals) support for cross-built projects

AFAIK there's no documentation available rn about using an editor (vscode) together with metals and have support for both Scala 2.x and Scala 3 in a single project. It would be nice if that rather common use case was supported and documented.

Revive `source:3.1-migration` documentation

Add a "Dotty 3.1 Migration Mode" page to document the -source:3.1-migration incompatibilities.
Move each description from this page to the corresponding readme in incompat-3.1 then include it in the "Dotty 3.1 Migration Mode" page using the mdoc modifier (see example).

Add this page in a "Going further" section.

Unexpected and undesirable Search functionality looking for "beanproperty"...

My first experience arriving at the home page is already undesirable and immediately diminished my migration confidence. It happened as a result of this thread:

Here's what happened:

1. Entering "beanproperty" in the search box did not cause anything to happen
2. Entering "bean property" in the search box caused a 404
3. Entering "bean" in the search box dropped me into a random location in the documentation
4. Attempting to find a place to submit an issue ticket was non-trivial

Given how simple these steps were to take, and given how unpredictable the results were, it leaves a terrible first impression.

I don't have the time (and for most others, the motivation) to try and figure these out as it would cause me to lose my current focus (evaluating a project migration LOE [Level Of Effort]) for which I came to this site in the first place.

404 link on the front page

https://scalacenter.github.io/scala-3-migration-guide/ links to https://scalacenter.github.io/scala-3-migration-guide/docs/scala-3-migration-mode.html which doesn't exist.

provide migration advice for early initializers

some previous discussion on this: scala/scala#8370

the Scala 2 warning (only emitted under -Xsource:3) says:

warning: early initializers are deprecated; they will be replaced by trait parameters in 3.0, see the migration guide on avoiding var/val in traits

at the time that message was written, no such migration guide existed, but now that this repo exists, I guess we can keep that wording :-)

scalafix ProcedureSyntax does not handle secondary constructor

Fix scalacenter/scalafix#1235 then update the incompatibility description accordingly.