Start migration guide

src/reference/SUMMARY.md

@@ -17,6 +17,7 @@
   - [sbt with IDEs](guide/IDE.md)
 - [Changes]()
   - [sbt 2.0 changes](changes/sbt-2.0-change-summary.md)
+  - [Migrating from sbt 1.x](changes/migrating-from-sbt-1.x.md)
 - [Concepts]()
   - [Caching](concepts/caching.md)
 - [Reference]()

src/reference/changes/migrating-from-sbt-1.x.md

@@ -0,0 +1,41 @@
+Migrating from sbt 1.x
+======================
+
+Changing the build to Scala 3.x
+-------------------------------
+
+Just so we're clear, users can build either Scala 2.x or Scala 3.x programs using either sbt 1.x or sbt 2.x. However, the Scala used that underlies `build.sbt` DSL is dictated by the sbt version. In sbt 2.0, we are migrating to Scala 3.x.
+
+This means that if you implement custom tasks or sbt plugins for sbt 2.x, it must be done using Scala 3.x. See [Scala 3.x incompatibility table][scala-incompatibility-table] the list of potential migration points.
+
+Bare settings changes
+---------------------
+
+```scala
+version := "0.1.0"
+scalaVersion := "{{scala3_example_version}}"
+```
+
+_Bare settings_, like the above, are settings that are written directly in `build.sbt` without `settings(...)`. In sbt 1.x bare settings were project settings that belong only to the root subproject. In sbt 2.x, the bare settings in `build.sbt` are common settings that are injected to **all subprojects**.
+
+### Migrating ThisBuild
+
+In sbt 2.x, settings scoped to `ThisBuild` should become a bare setting instead. One benefit of the new _common settings_ over `ThisBuild` is that it would act in a more predictable delegation since it would be inserted between the plugin settings and `settings(...)`, which means that it can used to define settings like `Compile / scalacOptions`, which was not possible with `ThisBuild`.
+
+Changes to `%%`
+---------------
+
+In sbt 2.x, `ModuleID`'s `%%` operator became platform-aware. For JVM subprojects, `%%` remains the same, which is used to encode Scala suffix such as `_3` on Maven repositories.
+
+### Migrating `%%%` operator
+
+When Scala.JS or Scala Native become available on sbt 2.x, `%%` encodes both the Scala version such as `_3` and the platform suffix such as `_sjs1`. This means that `%%%` can be replaced with `%%` instead.
+
+```scala
+libraryDependencies += "org.scala-js" %% "scalajs-dom" % "2.8.0"
+```
+
+Use `.platform(Platform.jvm)` in situations where JVM libraries are needed.
+
+
+  [scala-incompatibility-table]: https://docs.scala-lang.org/scala3/guides/migration/incompatibility-table.html