docs: update Scala 3 and derivation policy guidance

Author: MateuszKubuszok

.github/workflows/release.yml

@@ -23,7 +23,7 @@ jobs:
           passphrase: ${{ secrets.GPG_PASSPHRASE }}
       - uses: coursier/setup-action@v3.0.2
         with:
-          # Chimney 2.x targets -release 17 (Scala 3) / -release 11 (Scala 2.13) and its Scala 3.8 compiler
+          # Chimney 2.x targets -release 17 (Scala 3) / -release 11 (Scala 2.13) and its Scala 3.9 compiler
           # bridge is compiled for Java 17, so publishing must run on JDK 17+ (the old JDK 8 fails with
           # UnsupportedClassVersionError). The -release flags keep the emitted artifacts JDK 11/17 compatible.
           jvm: 'temurin:17'

.scala-steward.conf

@@ -1,11 +1,12 @@
 # add try-chimney to defaults from https://github.com/scala-steward-org/scala-steward/blob/main/docs/repo-specific-configuration.md
 updates.fileExtensions = [".mill-version",".sbt",".sbt.shared",".sc",".scala",".scalafmt.conf",".yml","build.properties","mill-version","pom.xml","try-chimney.sh"]
 
-# Per-artifact pins leak (Steward tracks binary-suffixed variants like scala3-library_sjs1_3),
-# so pin the whole group. Allows 3.9.x patch bumps; blocks cross-minor (3.9→3.10) and
-# Scala 2.13 bumps (2.13.x doesn't match the prefix, same effect as the old ignore).
-updates.pin = [
-  { groupId = "org.scala-lang", version = "3.9." }
+# Keep the Scala 3.9.0 and Scala 2.13 compiler/stdlib lines pinned and manage their updates manually.
+# Version pins are unreliable in a multi-version build because Steward can unify the two Scala lines,
+# while per-artifact ignores leak through binary-suffixed variants such as scala3-library_sjs1_3.
+# Ignoring the whole group reliably protects both supported compiler lines.
+updates.ignore = [
+  { groupId = "org.scala-lang" }
 ]
 pullRequests.grouping = [
   { name="scala-versions", "title"="Scala compiler updates", "filter"=[{"group" = "org.scala-lang"}, {"group" = "org.scoverage"}] }

README.md

@@ -15,7 +15,7 @@
 [![Scaladoc 2.13](https://javadoc.io/badge2/io.scalaland/chimney_2.13/scaladoc%202.13.svg)](https://javadoc.io/doc/io.scalaland/chimney_2.13)
 [![Scaladoc 3](https://javadoc.io/badge2/io.scalaland/chimney_3/scaladoc%203.svg)](https://javadoc.io/doc/io.scalaland/chimney_3)
 
-The battle-tested Scala library for data transformations. Supported for (2.13, 3.8.4+) x (JVM, Scala.js, Scala Native).
+The battle-tested Scala library for data transformations. Supported for (2.13, 3.9.0+) x (JVM, Scala.js, Scala Native).
 On the JVM, Scala 2.13 artifacts require JDK 11+ and Scala 3 artifacts require JDK 17+. Powered by [Hearth](https://github.com/kubuszok/hearth).
 
 Chimney documentation is available at https://chimney.readthedocs.io. Read the Docs keeps it versioned in case you need

build.sbt

@@ -458,8 +458,8 @@ lazy val chimneyCats = projectMatrix
     // Hearth StandardMacroExtension with IsCollection/IsMap providers for cats.data types (NonEmptyList, Chain, ...).
     // Test-scoped: it is consulted at MACRO-EXPANSION time of the TEST sources (ServiceLoader on the compile
     // classpath of the code being derived) - the specs prove cats collections derive WITHOUT chimney-cats implicits.
-    // NOTE: kindlings' Scala 3 artifacts are built with Scala 3.8.x (TASTy 28.8) - loading them requires chimney to
-    // build with Scala 3.8+ (older compilers throw "Forward incompatible TASTy file" from hearth's extension loading).
+    // NOTE: kindlings' Scala 3 artifacts are built with Scala 3.9.x (TASTy 28.9) - loading them requires chimney to
+    // build with Scala 3.9+ (older compilers throw "Forward incompatible TASTy file" from hearth's extension loading).
     // Since hearth#325 (0.4.1) an unloadable extension jar is SKIPPED gracefully instead of poisoning every derivation
     // in the module - but the specs here obviously still need the extension to actually load.
     libraryDependencies += "com.kubuszok" %% "kindlings-cats-integration" % versions.kindlingsCatsIntegration % Test

chimney-cats/src/test/scala/io/scalaland/chimney/cats/CatsDataSpec.scala

@@ -25,8 +25,8 @@ import io.scalaland.chimney.utils.OptionUtils.*
   *   - `NonEmptyMap`/`NonEmptySet` require `cats.Order` of the key/element to be summonable at MACRO-EXPANSION time
   *     (1.x required `Ordering` at implicit-summoning time - same effective requirement, different mechanism).
   *
-  * Kindlings' Scala 3 artifacts are built with Scala 3.8.x (TASTy 28.8) - readable now that chimney builds with Scala
-  * 3.8.4+, so this spec is SHARED between both Scala versions.
+  * Kindlings' Scala 3 artifacts are built with Scala 3.9.x (TASTy 28.9) - readable now that chimney builds with Scala
+  * 3.9.0+, so this spec is SHARED between both Scala versions.
   */
 class CatsDataSpec extends ChimneySpec {
 

docs/docs/cheatsheet.md

@@ -62,7 +62,9 @@ This section is short summary of all Chimney features (described in more detail
     compilation time) and avoids unnecessary boxing with `partial.Result`.
 
     Chimney 2.x no longer provides `io.scalaland.chimney.auto._`. Automatic derivation is provided from the type-class
-    companions, while `syntax._` and `inlined._` let you choose which extension methods to import.
+    companions, while `syntax._` and `inlined._` let you choose which extension methods to import. Use the
+    [derivation policy](cookbook.md#derivation-policy-restricting-where-derivation-may-happen) to restrict structural
+    derivation to designated scopes.
 
 !!! example "Partial Results"
 

docs/docs/cookbook.md

@@ -751,9 +751,9 @@ are described in each type's section.
     had a bad experience (long compilation times, poor performance) with the automatic derivation, please note that
     Chimney derivation DOES NOT work the same way, so your experiences are unlikely to carry over to Chimney.
 
-    Please, read the section below, as it will explain why replacing `import io.scalaland.chimney.dsl._` with
-    `Transformer.derive` + `import io.scalaland.chimney.syntax._` + `import io.scalaland.chimney.auto._` (the last one only available on 1.x line)
-    might actually *degrade* the performance, instead of improving it.
+    Please read the section below: it explains why Chimney's automatic derivation does not have the usual performance
+    problem. On Chimney 2.x, `io.scalaland.chimney.auto._` no longer exists; if you need to restrict where automatic
+    derivation may happen, use the [derivation policy](#derivation-policy-restricting-where-derivation-may-happen).
 
     In depth explanation why automatic derivation is slow (when it's slow!) and how Chimney avoided such slowdown can be
     found in [*Slow-Auto, Inconvenient-Semi: escaping false dichotomy with sanely-automatic derivation*](https://mateuszkubuszok.github.io/SlowAutoInconvenientSemi/)
@@ -819,26 +819,27 @@ The last property is a reason many projects encourage the usage of semiautomatic
 and many libraries provide automatic derivation as a quick and dirty way of doing things
 requiring an opt-in.
 
-Chimney's defaults for (good) historical reasons mix these 2 modes (and one more, which
-will describe in a moment), but (_due to popular demand_) it also allows you to selectively
-use these imports
+On the 1.x line, Chimney's defaults mixed these two modes (and one more, described below), but also allowed users to
+compose these imports selectively:
 
 !!! example
 
     ```scala
-    import io.scalaland.chimney.auto._ // Not available on Chimney 2.+, see below
+    import io.scalaland.chimney.auto._ // 1.x only
     import io.scalaland.chimney.inlined._
     import io.scalaland.chimney.syntax._
     ```
 
-instead of `io.scalaland.chimney.dsl` to achieve a similar behavior:
+instead of `io.scalaland.chimney.dsl` to achieve a similar behavior. On 2.x, `syntax._` and `inlined._` remain
+available, while automatic derivation is provided directly by the `Transformer`, `PartialTransformer`, and `Patcher`
+companions:
 
   - if you `import io.scalaland.chimney.syntax._` it will expose only extension
     methods working with type classes (`Transformer`, `PartialTransformer` and `Patcher`),
     but with no derivation
 
-  - if you `import io.scalaland.chimney.auto._` it will only provide implicit instances
-    generated through derivation.
+  - on 1.x, `import io.scalaland.chimney.auto._` provided implicit instances generated through derivation. This
+    separate import does not exist on 2.x.
 
     Semiautomatic derivation was available for a long time using methods:
 
@@ -955,9 +956,8 @@ or there is none and macro will handle recursion internally.
     This also allows to replace a bunch of anonymous instances calling one another with a single
     instance - limitting the number of allocations and improving performance.
 
-However, with `import io.scalaland.chimney.auto._` the same semantics as in other
-libraries is used: `implicit def` returns `Transformer`, so if derivation with defaults
-is possible it will always be triggered.
+Prior to 2.0.0, `import io.scalaland.chimney.auto._` used the same semantics as automatic derivation in other
+libraries: an `implicit def` returned a `Transformer`, so derivation with defaults was triggered whenever possible.
 
 !!! important
 
@@ -983,7 +983,7 @@ is possible it will always be triggered.
     ```scala
     trait TypeClass[A]
     object TypeClass {
-      inline given derived[A]: AutoDerived[A] =
+      inline given derived[A]: TypeClass[A] =
         ${ macroUsingSimmonIgnoring[A] }
         // Inside it uses:
         // Expr.summonIgnoring[TypeClass[A]](
@@ -994,7 +994,7 @@ is possible it will always be triggered.
     extension [A](value: A) def foo(using TypeClass[A]) = ...
     ```
 
-    For that reason `import io.scalaland.chimney.auto._` does not exists on Chimney 2.0.0 for Scala 3.
+    For that reason `import io.scalaland.chimney.auto._` does not exist on Chimney 2.0.0 for Scala 3.
 
     And thanks to porting the solution from Scala 3.7.0 to 2.13.17, Scala 2.13 could have align the API
     again - removing `import io.scalaland.chimney.auto._` as well in the process. (The other consequence
@@ -1008,7 +1008,7 @@ provide `implicitConflictResolution` flag.
 
 !!! note
 
-    In other words, replicating the setup where you do:
+    In other words, on Chimney 1.x, replicating the setup where you do:
 
     ```scala
     implicit val transformer: Transformer[From, To] = locally {
@@ -1030,11 +1030,10 @@ provide `implicitConflictResolution` flag.
 
 For the reasons above the recommendations are as follows:
 
-  - if you care about performance, use either inlined derivation (`.into.transform`, for a one-time-usage) or
-    semi-automatic derivation with recursion handled in the macro(`.derive`/`.define.build*` + `syntax._`, without
-    importing `auto._`)
-  - only use `import auto._` when you want predictable behavior similar to other libraries
-    (predictably bad)
+  - if you care about performance, use either inlined derivation (`.into.transform`, for a one-time usage) or
+    semiautomatic derivation with recursion handled in the macro (`.derive`/`.define.build*` + `syntax._`)
+  - on Chimney 2.x, use the [derivation policy](#derivation-policy-restricting-where-derivation-may-happen) when you
+    need to prevent ad-hoc structural derivation outside designated scopes
   - use unit tests to ensure, that your code does what it should do
   - use benchmarks to ensure it is reasonably fast
   - and keep on using `import dsl._` until you have some good proof that (recursive) semi-automatic derivation is needed 
@@ -1051,6 +1050,10 @@ canonical mapping is defined in one designated place rather than materialized ad
 **derivation policy** provides this without a separate semi-automatic API: it is a compile-time switch configured
 entirely through `-Xmacro-settings`.
 
+On Chimney 2.x this is the replacement for controlling automatic derivation through selective
+`import io.scalaland.chimney.auto._` imports. The `auto` package no longer exists; derivation is available through the
+unified type classes, and this policy decides where their macros may generate new structural transformations.
+
 The policy gates only **structural derivation** — generating new transformation code for a `case class` or a `sealed`
 hierarchy / `enum`. Everything else keeps working unconditionally: pre-existing implicits (your hand-written
 `Transformer`s), subtype upcasts, options, eithers, collections, value classes.
@@ -1549,8 +1552,9 @@ With it on the classpath you can:
 !!! warning "Scala 3 status"
 
     A macro extension must be **loadable by the compiler that expands the macro**, so its TASTy version matters:
-    `kindlings-cats-integration` `{{ libraries.kindlings }}`'s Scala 3 artifacts are built with Scala 3.8, which is
-    why Chimney `2.0.0` itself is built with Scala 3.8.4+ - the integration works on **both** Scala 2.13 and Scala 3.
+    `kindlings-cats-integration` `{{ libraries.kindlings }}`'s Scala 3 artifacts are built with Scala 3.9.0, which is
+    why Chimney `2.0.0` itself is built with Scala 3.9.0 (TASTy 28.9) - the integration works on **both** Scala 2.13
+    and Scala 3.
 
 !!! example "Converting from Cats collections"
 

docs/docs/quickstart.md

@@ -1,6 +1,6 @@
 # Quick Start
 
-Chimney is supported for Scala **2.13**, **3.8.4+** on [**JVM**](https://www.scala-lang.org/),
+Chimney is supported for Scala **2.13**, **3.9.0+** on [**JVM**](https://www.scala-lang.org/),
 [**Scala.js**](https://www.scala-js.org/) and [**Scala Native**](https://scala-native.org/) with full feature parity
 between each version.
 

docs/docs/troubleshooting.md

@@ -44,8 +44,8 @@ If you:
 
 Scala 2.12 support was dropped, so if you want to migrate to 2.x, we recommend migrating to 1.x before.
 
-On Scala 3 the minimal supported compiler version was raised from 3.3 (LTS) to **3.8.4** - the artifacts are built
-with Scala 3.8.4 (TASTy 28.8), so older Scala 3 compilers cannot consume them.
+On Scala 3 the minimum supported compiler version was raised from 3.3 (LTS) to **3.9.0** - the artifacts are built
+with Scala 3.9.0 (TASTy 28.9), so older Scala 3 compilers cannot consume them.
 
 On the JVM, JDK requirements were raised: Scala 2.13 artifacts require **JDK 11+** and Scala 3 artifacts require
 **JDK 17+** (Chimney's macros are built on top of [Hearth](https://scala-hearth.readthedocs.io/), which is JDK 11+).
@@ -56,7 +56,13 @@ Chimney 2.0.0 no longer requires distinction between:
  - `PartialTransformer` and `PartialTransformer.AutoDerived`
  - `Patcher` and `Patcher.AutoDerived`
 
-to make migration easier, `AutoDerived` still exist but as a type alias.
+To make migration easier, the `AutoDerived` names still exist as type aliases.
+
+The separate `import io.scalaland.chimney.auto._` was also removed. Automatic derivation is now provided by the same
+`Transformer`, `PartialTransformer`, and `Patcher` types used for explicitly defined instances. If you previously
+controlled automatic derivation by importing `auto._` only in selected scopes, configure the
+[derivation policy](cookbook.md#derivation-policy-restricting-where-derivation-may-happen) instead. It can allow
+structural derivation only in designated packages, objects, or classes, with an optional local opt-in import.
 
 Breaking changes in API:
 

scripts/test-snippets.scala

@@ -1,4 +1,4 @@
-//> using scala 3.3.8
+//> using scala 3.9.0
 //> using dep com.kubuszok::scala-cli-md-spec:0.2.1
 //> using dep org.virtuslab::scala-yaml:0.3.3