Documented ammoniteVersion and print some warning when resolving ammonite

docs/antora/modules/ROOT/pages/Configuring_Mill.adoc

@@ -615,3 +615,35 @@ object foo extends ScalaModule {
 You can also override `unmanagedClasspath` to point it at jars that you want to
 download from arbitrary URLs. Note that targets like `unmanagedClasspath` are
 cached, so your jar is downloaded only once and re-used indefinitely after that.
+
+
+== Using the Ammonite Repl / Scala console
+
+All ``ScalaModule``s have a `console` and a `repl` target, to start a Scala console or an Ammonite Repl.
+
+To use the latter, you can (and sometimes need to) customize the Ammonite version to work with your selected Scala version.
+The default Ammonite version is the one, which is used by Mill internally (Mill's `build.sc` is an Ammonite script, after all).
+But depending on the Scala version you are using, there is probably no matching Ammonite release available.
+In order to start the repl, you have to specify a different available Ammonite version.
+
+.Example: Overriding `ammoniteVersion` to select a release compatible to the `scalaVersion`
+[source,scala]
+----
+import mill._. scalalib._
+
+object foo extends ScalaModule {
+  def scalaVersion = "2.12.6"
+  def ammoniteVersion = "2.4.0"
+}
+----
+
+[TIP]
+--
+_Why is Ammonite tied to the exact Scala version?_
+
+This is because Ammonite depends on the Scala compiler.
+In contrast to the Scala library, compiler releases do not guarantee any binary compatibility between releases.
+As a consequence, Ammonite needs full Scala version specific releases.
+
+The older your used Mill version or the newer the Scala version you want to use, the higher is the risk that the default Ammonite version will not match.
+--

scalalib/src/ScalaModule.scala

@@ -347,7 +347,9 @@ trait ScalaModule extends JavaModule { outer =>
    * Ammonite's version used in the `repl` command is by default
    * set to the one Mill is built against.
    */
-  def ammoniteVersion: T[String] = T(Versions.ammonite)
+  def ammoniteVersion: T[String] = T {
+    Versions.ammonite
+  }
 
   /**
    * Dependencies that are necessary to run the Ammonite Scala REPL
@@ -361,14 +363,23 @@ trait ScalaModule extends JavaModule { outer =>
 
   def resolvedAmmoniteReplIvyDeps = T {
     resolveDeps(T.task {
+      val scaVersion = scalaVersion()
+      val ammVersion = ammoniteVersion()
+      if (scaVersion != BuildInfo.scalaVersion && ammVersion == Versions.ammonite) {
+        T.log.info(
+          s"""Resolving Ammonite Repl ${ammVersion} for Scala ${scaVersion} ...
+             |If you encounter dependency resolution failures, please review/override `def ammoniteVersion` to select a compatible release.""".stripMargin
+        )
+      }
       runIvyDeps() ++ transitiveIvyDeps() ++
-        Agg(ivy"com.lihaoyi:::ammonite:${ammoniteVersion()}")
+        Agg(ivy"com.lihaoyi:::ammonite:${ammVersion}")
     })()
   }
 
   /**
    * Opens up an Ammonite Scala REPL with your module and all dependencies present,
-   * for you to test and operate your code interactively
+   * for you to test and operate your code interactively.
+   * Use [[ammoniteVersion]] to customize the Ammonite version to use.
    */
   def repl(replOptions: String*): Command[Unit] = T.command {
     if (T.log.inStream == DummyInputStream) {