Merge pull request #1273 from eed3si9n/wip/update-migration-guide

[2.x] Update migration guide

book.toml

@@ -20,7 +20,8 @@ cname = "www.scala-sbt.org"
 [preprocessor.variables.variables]
 sbt_version = "2.0.0-M3"
 sbt_runner_version = "1.10.0"
-scala3_example_version = "3.3.3"
+scala3_example_version = "3.6.2"
+scala3_metabuild_version = "3.6.2"
 scala2_13_example_version = "2.13.15"
 
 [preprocessor.admonish]

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

@@ -102,6 +102,23 @@ libraryDependencies += "org.scala-js" %% "scalajs-dom" % "2.8.0"
 
 Use `.platform(Platform.jvm)` in case where JVM libraries are needed.
 
+Changes to `target`
+-------------------
+
+In sbt 2.x, the `target` directory is unified to be a single `target/` directory in the working directory, and each subproject creates a subdirectory encoding platform, Scala version, and the subproject id. To absorb this change in scripted tests, `exists`, `absent`, and `delete` now supports glob expression `**`, as well as `||`.
+
+```bash
+# before
+$ absent target/out/jvm/scala-3.3.1/clean-managed/src_managed/foo.txt
+$ exists target/out/jvm/scala-3.3.1/clean-managed/src_managed/bar.txt
+
+# after
+$ absent target/**/src_managed/foo.txt
+$ exists target/**/src_managed/bar.txt
+
+# either is ok
+$ exists target/**/proj/src_managed/bar.txt || proj/target/**/src_managed/bar.txt
+```
 
 The PluginCompat technique
 --------------------------

src/reference/changes/sbt-2.0-change-summary.md

@@ -15,13 +15,16 @@ Changes with compatibility implications
 
 See also [Migrating from sbt 1.x](./migrating-from-sbt-1.x.md).
 
-- sbt 2.x uses Scala 3.x for build definitions and plugins (Both sbt 1.x and 2.x are capable of building Scala 2.x and 3.x) by [@eed3si9n][@eed3si9n], [@adpi2][@adpi2], and others.
+- sbt 2.x uses Scala 3.x (currently **{{scala3_metabuild_version}}**) for build definitions and plugins (Both sbt 1.x and 2.x are capable of building Scala 2.x and 3.x) by [@eed3si9n][@eed3si9n], [@adpi2][@adpi2], and others.
 - Bare settings are added to all subprojects, as opposed to just the root subproject, and thus replacing the role that `ThisBuild` has played.
 - `test` task is changed to be incremental test that can cache test results. Use `testFull` for full test by [@eed3si9n][@eed3si9n] in [#7686][7686]
+- Default settings and tasks keys typed to `URL` `apiMappings`, `apiURL`, `homepage`, `organizationHomepage`, `releaseNotesURL` were changed to `URI` in [#7927](https://github.com/sbt/sbt/pull/7927).
+- `licenses` key is changed from `Seq[(String, URL)]` to `Seq[License]` in [#7927](https://github.com/sbt/sbt/pull/7927).
 - sbt 2.x plugins are published with `_sbt2_3` suffix by [@eed3si9n][@eed3si9n] in [#7671][7671]
 - sbt 2.x adds `platform` setting so `ModuleID`'s `%%` operator can cross build on JVM as well as JS and Native, as opposed to `%%%` operator that was created in a plugin to workaround this issue, by [@eed3si9n][@eed3si9n] in [#6746][6746]
 - Dropped `useCoursier` setting so Coursier cannot be opted out, by [@eed3si9n][@eed3si9n] in [#7712][7712]
 - `Key.Classpath` is changed to be an alias of the `Seq[Attributed[xsbti.HashedVirtualFileRef]]` type, instead of `Seq[Attributed[File]]`. Similarly, some task keys that used to return `File` have changed to return `HashedVirtualFileRef` instead. See [Caching Files].
+- In sbt 2.x `target` defaults to `target/out/jvm/scala-{{scala3_metabuild_version}}/<subproject>/`, as opposed to `<subproject>/target/`.
 
 ### Dropped dreprecations