Mention potential gotchas in the migration guide

[rachitnigam]

I recently ported a project from Scala 2 to Scala 3 with some modules using Scala 2 and others using Scala 3. I ran into several gotchas that might be worth talking about in the docs somewhere. The entire migration process used sbt and sbt-migrate.

1. My Scala 2 project was using 2.13.6 while the latest sbt-migrate attempts to migrate projects to 3.1.*. Once the migration commands are completed, compilation failed because 2.13.6 TastY reader cannot read class files compiled with 3.1 (as far as I can tell). The error message was confusion since it just gave me the major/minor versions that TastY was expecting without explaining what I can do to fix it or what could be a potential cause.
2. After migration, I attempted to convert some sealed trait definitions into enum but the compiler kept rejecting the syntax. 2a. While attempting to fix this problem, I separately discovered the -new-syntax, -indent, and -rewrite flags. The migration docs should probably link to that page as a good next step once a module is migrated to Scala 3. 2b. Eventually, someone on the gitter channel pointed out the sbt-migrate sets the -source:3.0-migration option which causes the compiler to reject the new constructs. Disabling the plugin made my code work.

[julienrf]

Thank you for reporting. About the first point, I believe there should be a compatibility matrix showing which version of Scala 2.13 supports which version of Scala 3, in https://docs.scala-lang.org/scala3/guides/migration/compatibility-classpath.html#the-scala-213-tasty-reader. (Most likely, Scala 2.13.8 supports Scala 3.1)