From 1e99ee5742239a51c8c98e01ff20d6159ef2670c Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:01:36 -0700
Subject: [PATCH 01/13] .

---
 scalalib/src/mill/scalalib/TestModule.scala | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index 253ea1b5450..776c34a366b 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -123,6 +123,16 @@ trait TestModule
    */
   def testReportXml: T[Option[String]] = T(Some("test-report.xml"))
 
+  /**
+   * Whether or not to use the test task destination folder as the working directory
+   * when running tests. `true` means test subprocess run in the `.dest/` folder of
+   * the test task, providing better isolation and encouragement of best practices
+   * (e.g. not reading/writing stuff randomly from the project source tree). `false`
+   * means the test subprocess runs in the project root folder, providing weaker
+   * isolation.
+   */
+  def testUseDestAsWorkDir: T[Boolean] = true
+
   /**
    * The actual task shared by `test`-tasks that runs test in a forked JVM.
    */
@@ -182,7 +192,7 @@ trait TestModule
         jvmArgs = jvmArgs,
         envArgs = forkEnv(),
         mainArgs = mainArgs,
-        workingDir = forkWorkingDir(),
+        workingDir = if (testUseDestAsWorkDir()) T.dest else forkWorkingDir(),
         useCpPassingJar = useArgsFile
       )
 

From f5b54dc9e76233994d21061a35f157e6c1abca95 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:05:41 -0700
Subject: [PATCH 02/13] .

---
 scalalib/src/mill/scalalib/TestModule.scala | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index 776c34a366b..b118686fed5 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -23,7 +23,7 @@ trait TestModule
   def compile: T[mill.scalalib.api.CompilationResult]
 
   override def defaultCommandName() = "test"
-
+  def resources: T[Seq[PathRef]]
   /**
    * The classpath containing the tests. This is most likely the output of the compilation target.
    * By default this uses the result of [[localRunClasspath]], which is most likely the result of a local compilation.
@@ -190,7 +190,9 @@ trait TestModule
             _.path
           ),
         jvmArgs = jvmArgs,
-        envArgs = forkEnv(),
+        envArgs =
+          Map("MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";")) ++
+          forkEnv(),
         mainArgs = mainArgs,
         workingDir = if (testUseDestAsWorkDir()) T.dest else forkWorkingDir(),
         useCpPassingJar = useArgsFile

From 8a9fee7de59851ca41d016759d26f3eddb8fc6b8 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:10:22 -0700
Subject: [PATCH 03/13] .

---
 scalalib/src/mill/scalalib/TestModule.scala | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index b118686fed5..b139ef2d3b3 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -183,6 +183,7 @@ trait TestModule
       os.write(argsFile, upickle.default.write(testArgs))
       val mainArgs = Seq(testRunnerClasspathArg, argsFile.toString)
 
+      os.makeDir(T.dest / "test-workspace")
       Jvm.runSubprocess(
         mainClass = "mill.testrunner.entrypoint.TestRunnerMain",
         classPath =
@@ -194,7 +195,7 @@ trait TestModule
           Map("MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";")) ++
           forkEnv(),
         mainArgs = mainArgs,
-        workingDir = if (testUseDestAsWorkDir()) T.dest else forkWorkingDir(),
+        workingDir = if (testUseDestAsWorkDir()) T.dest / "test-workspace" else forkWorkingDir(),
         useCpPassingJar = useArgsFile
       )
 

From 7211d56f84836b8ff59d08eaf98552bc553a05f7 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:18:46 -0700
Subject: [PATCH 04/13] .

---
 scalalib/src/mill/scalalib/TestModule.scala | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index b139ef2d3b3..8fa196a7b07 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -183,7 +183,7 @@ trait TestModule
       os.write(argsFile, upickle.default.write(testArgs))
       val mainArgs = Seq(testRunnerClasspathArg, argsFile.toString)
 
-      os.makeDir(T.dest / "test-workspace")
+      os.makeDir(T.dest / "sandbox")
       Jvm.runSubprocess(
         mainClass = "mill.testrunner.entrypoint.TestRunnerMain",
         classPath =
@@ -195,7 +195,7 @@ trait TestModule
           Map("MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";")) ++
           forkEnv(),
         mainArgs = mainArgs,
-        workingDir = if (testUseDestAsWorkDir()) T.dest / "test-workspace" else forkWorkingDir(),
+        workingDir = if (testUseDestAsWorkDir()) T.dest / "sandbox" else forkWorkingDir(),
         useCpPassingJar = useArgsFile
       )
 

From 7fb0022ad72bb671221e5d40cc186b17fc94792b Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:21:04 -0700
Subject: [PATCH 05/13] .

---
 scalalib/src/mill/scalalib/TestModule.scala | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index 8fa196a7b07..ec98eb51bee 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -125,13 +125,13 @@ trait TestModule
 
   /**
    * Whether or not to use the test task destination folder as the working directory
-   * when running tests. `true` means test subprocess run in the `.dest/` folder of
+   * when running tests. `true` means test subprocess run in the `.dest/sandbox` folder of
    * the test task, providing better isolation and encouragement of best practices
    * (e.g. not reading/writing stuff randomly from the project source tree). `false`
    * means the test subprocess runs in the project root folder, providing weaker
    * isolation.
    */
-  def testUseDestAsWorkDir: T[Boolean] = true
+  def testSandboxWorkingDir: T[Boolean] = true
 
   /**
    * The actual task shared by `test`-tasks that runs test in a forked JVM.
@@ -195,7 +195,7 @@ trait TestModule
           Map("MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";")) ++
           forkEnv(),
         mainArgs = mainArgs,
-        workingDir = if (testUseDestAsWorkDir()) T.dest / "sandbox" else forkWorkingDir(),
+        workingDir = if (testSandboxWorkingDir()) T.dest / "sandbox" else forkWorkingDir(),
         useCpPassingJar = useArgsFile
       )
 

From 16f69f776e6513ba0578b793fe1841f821ea094c Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:26:00 -0700
Subject: [PATCH 06/13] .

---
 scalalib/src/mill/scalalib/TestModule.scala | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index ec98eb51bee..c744bff1b45 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -24,6 +24,7 @@ trait TestModule
 
   override def defaultCommandName() = "test"
   def resources: T[Seq[PathRef]]
+
   /**
    * The classpath containing the tests. This is most likely the output of the compilation target.
    * By default this uses the result of [[localRunClasspath]], which is most likely the result of a local compilation.
@@ -193,7 +194,7 @@ trait TestModule
         jvmArgs = jvmArgs,
         envArgs =
           Map("MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";")) ++
-          forkEnv(),
+            forkEnv(),
         mainArgs = mainArgs,
         workingDir = if (testSandboxWorkingDir()) T.dest / "sandbox" else forkWorkingDir(),
         useCpPassingJar = useArgsFile

From 8ea782e1db66f9fa2aea8edf6c17b7eb193276a6 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Wed, 7 Aug 2024 21:29:56 -0700
Subject: [PATCH 07/13] .

---
 scalalib/src/mill/scalalib/JavaModule.scala | 1 +
 scalalib/src/mill/scalalib/TestModule.scala | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/scalalib/src/mill/scalalib/JavaModule.scala b/scalalib/src/mill/scalalib/JavaModule.scala
index fa94ed339fa..60c201e3c67 100644
--- a/scalalib/src/mill/scalalib/JavaModule.scala
+++ b/scalalib/src/mill/scalalib/JavaModule.scala
@@ -42,6 +42,7 @@ trait JavaModule
     // Run some consistence checks
     hierarchyChecks()
 
+    override def resources = super[JavaModule].resources
     override def moduleDeps: Seq[JavaModule] = Seq(outer)
     override def repositoriesTask: Task[Seq[Repository]] = outer.repositoriesTask
     override def resolutionCustomizer: Task[Option[coursier.Resolution => coursier.Resolution]] =
diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index c744bff1b45..37d6fc70825 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -23,7 +23,7 @@ trait TestModule
   def compile: T[mill.scalalib.api.CompilationResult]
 
   override def defaultCommandName() = "test"
-  def resources: T[Seq[PathRef]]
+  def resources: T[Seq[PathRef]] = T{ Seq.empty[PathRef] }
 
   /**
    * The classpath containing the tests. This is most likely the output of the compilation target.

From 84cebd386c4cef5a3b33c796d83935708b85d5ff Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Thu, 8 Aug 2024 09:00:30 -0700
Subject: [PATCH 08/13] .

---
 scalajslib/src/mill/scalajslib/ScalaJSModule.scala             | 2 +-
 scalalib/src/mill/scalalib/TestModule.scala                    | 1 -
 scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala | 1 +
 3 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/scalajslib/src/mill/scalajslib/ScalaJSModule.scala b/scalajslib/src/mill/scalajslib/ScalaJSModule.scala
index 6a273c04f9a..c6e98a5555b 100644
--- a/scalajslib/src/mill/scalajslib/ScalaJSModule.scala
+++ b/scalajslib/src/mill/scalajslib/ScalaJSModule.scala
@@ -337,7 +337,7 @@ trait ScalaJSModule extends scalalib.ScalaModule { outer =>
 }
 
 trait TestScalaJSModule extends ScalaJSModule with TestModule {
-
+  override def resources = super[ScalaJSModule].resources
   def scalaJSTestDeps = T {
     defaultResolver().resolveDeps(
       Loose.Agg(
diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index eba738ac9eb..ed34c67fe51 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -196,7 +196,6 @@ trait TestModule
           "MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";"),
           "MILL_TEST_DEST_FOLDER" -> T.dest.toString()
         ) ++ forkEnv(),
-        envArgs = Map() ++ forkEnv(),
         mainArgs = mainArgs,
         workingDir = if (testSandboxWorkingDir()) T.dest / "sandbox" else forkWorkingDir(),
         useCpPassingJar = useArgsFile
diff --git a/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala b/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala
index e76625ff5df..fab09ddae9c 100644
--- a/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala
+++ b/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala
@@ -341,6 +341,7 @@ trait ScalaNativeModule extends ScalaModule { outer =>
 }
 
 trait TestScalaNativeModule extends ScalaNativeModule with TestModule {
+  override def resources = super[ScalaNativeModule].resources
   override def testLocal(args: String*) = T.command { test(args: _*) }
   override protected def testTask(
       args: Task[Seq[String]],

From 88a6379aa4b73b8f709b5bf5d24588c7f6b9023b Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Thu, 8 Aug 2024 09:33:24 -0700
Subject: [PATCH 09/13] .

---
 scalajslib/src/mill/scalajslib/ScalaJSModule.scala            | 3 ++-
 scalalib/src/mill/scalalib/TestModule.scala                   | 2 +-
 .../src/mill/scalanativelib/ScalaNativeModule.scala           | 4 +++-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/scalajslib/src/mill/scalajslib/ScalaJSModule.scala b/scalajslib/src/mill/scalajslib/ScalaJSModule.scala
index c6e98a5555b..35514aee6f1 100644
--- a/scalajslib/src/mill/scalajslib/ScalaJSModule.scala
+++ b/scalajslib/src/mill/scalajslib/ScalaJSModule.scala
@@ -12,6 +12,7 @@ import mill.scalajslib.api._
 import mill.scalajslib.internal.ScalaJSUtils.getReportMainFilePathRef
 import mill.scalajslib.worker.{ScalaJSWorker, ScalaJSWorkerExternalModule}
 import mill.scalalib.bsp.{ScalaBuildTarget, ScalaPlatform}
+import mill.T
 
 trait ScalaJSModule extends scalalib.ScalaModule { outer =>
 
@@ -337,7 +338,7 @@ trait ScalaJSModule extends scalalib.ScalaModule { outer =>
 }
 
 trait TestScalaJSModule extends ScalaJSModule with TestModule {
-  override def resources = super[ScalaJSModule].resources
+  override def resources: T[Seq[PathRef]] = super[ScalaJSModule].resources
   def scalaJSTestDeps = T {
     defaultResolver().resolveDeps(
       Loose.Agg(
diff --git a/scalalib/src/mill/scalalib/TestModule.scala b/scalalib/src/mill/scalalib/TestModule.scala
index ed34c67fe51..283fa37d470 100644
--- a/scalalib/src/mill/scalalib/TestModule.scala
+++ b/scalalib/src/mill/scalalib/TestModule.scala
@@ -23,7 +23,7 @@ trait TestModule
   def compile: T[mill.scalalib.api.CompilationResult]
 
   override def defaultCommandName() = "test"
-  def resources: T[Seq[PathRef]] = T{ Seq.empty[PathRef] }
+  def resources: T[Seq[PathRef]] = T { Seq.empty[PathRef] }
 
   /**
    * The classpath containing the tests. This is most likely the output of the compilation target.
diff --git a/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala b/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala
index fab09ddae9c..8e4a1646da6 100644
--- a/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala
+++ b/scalanativelib/src/mill/scalanativelib/ScalaNativeModule.scala
@@ -22,6 +22,8 @@ import mill.scalalib.{
 import mill.testrunner.{TestResult, TestRunner, TestRunnerUtils}
 import mill.scalanativelib.api._
 import mill.scalanativelib.worker.{ScalaNativeWorkerExternalModule, api => workerApi}
+import mill.T
+import mill.api.PathRef
 
 trait ScalaNativeModule extends ScalaModule { outer =>
   def scalaNativeVersion: T[String]
@@ -341,7 +343,7 @@ trait ScalaNativeModule extends ScalaModule { outer =>
 }
 
 trait TestScalaNativeModule extends ScalaNativeModule with TestModule {
-  override def resources = super[ScalaNativeModule].resources
+  override def resources: T[Seq[PathRef]] = super[ScalaNativeModule].resources
   override def testLocal(args: String*) = T.command { test(args: _*) }
   override protected def testTask(
       args: Task[Seq[String]],

From 053e91f6fb8d7c902c4b7bc023997446a4226970 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Thu, 8 Aug 2024 11:40:02 -0700
Subject: [PATCH 10/13] .

---
 build.sc                               | 13 +++++++------
 example/thirdparty/commons-io/build.sc |  1 +
 example/thirdparty/netty/build.sc      |  2 +-
 3 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/build.sc b/build.sc
index 56cc7fa6e3c..e7ba19acfd7 100644
--- a/build.sc
+++ b/build.sc
@@ -236,12 +236,13 @@ def millLastTag: T[String] = T {
 }
 
 def millBinPlatform: T[String] = T {
-  val tag = millLastTag()
-  if (tag.contains("-M")) tag
-  else {
-    val pos = if (tag.startsWith("0.")) 2 else 1
-    tag.split("[.]", pos + 1).take(pos).mkString(".")
-  }
+//  val tag = millLastTag()
+//  if (tag.contains("-M")) tag
+//  else {
+//    val pos = if (tag.startsWith("0.")) 2 else 1
+//    tag.split("[.]", pos + 1).take(pos).mkString(".")
+//  }
+  "0.11"
 }
 
 def baseDir = build.millSourcePath
diff --git a/example/thirdparty/commons-io/build.sc b/example/thirdparty/commons-io/build.sc
index 34097510b6f..5f65af34b97 100644
--- a/example/thirdparty/commons-io/build.sc
+++ b/example/thirdparty/commons-io/build.sc
@@ -15,6 +15,7 @@ object commonsio extends RootModule with PublishModule with MavenModule {
   )
 
   object test extends MavenTests with TestModule.Junit5 with  JmhModule{
+    def testSandboxWorkingDir = false
     def jmhCoreVersion = "1.37"
     def ivyDeps = super.ivyDeps() ++ Agg(
       ivy"org.junit.jupiter:junit-jupiter:5.10.3",
diff --git a/example/thirdparty/netty/build.sc b/example/thirdparty/netty/build.sc
index 9b24c962484..cd001231ebf 100644
--- a/example/thirdparty/netty/build.sc
+++ b/example/thirdparty/netty/build.sc
@@ -13,7 +13,7 @@ trait NettyBaseModule extends MavenModule{
   def javacOptions = Seq("-source", "1.8", "-target", "1.8")
 }
 trait NettyBaseTestSuiteModule extends NettyBaseModule with TestModule.Junit5{
-
+  def testSandboxWorkingDir = false
   def testFramework = "com.github.sbt.junit.jupiter.api.JupiterFramework"
   def ivyDeps = Agg(
     ivy"com.github.sbt.junit:jupiter-interface:0.11.2",

From 430d7054995fde83cbbd6f944babf6bb3ffab237 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Sat, 10 Aug 2024 15:48:32 -0700
Subject: [PATCH 11/13] .

---
 .../ROOT/pages/Java_Module_Config.adoc        |  19 ++---
 .../ROOT/pages/Scala_Module_Config.adoc       |  18 +++--
 .../build.sc                                  |   0
 .../src/foo/Foo.java                          |   0
 .../textfile.txt                              |   0
 .../bar/resources/application.conf            |   0
 .../build.sc                                  |   0
 .../foo/resources/application.conf            |   0
 .../foo/src/foo/Foo.java                      |   0
 .../build.sc                                  |   0
 .../foo/src/foo/Foo.java                      |   0
 .../javamodule/{12-jni => 13-jni}/build.sc    |   0
 .../native-src/HelloWorld.c                   |   0
 .../src/foo/HelloWorld.java                   |   0
 .../test/src/foo/HelloWorldTest.java          |   0
 .../bar/src/bar/GetterSetterExample.java      |   0
 .../bar/test/src/bar/HelloWorldTest.java      |   0
 .../build.sc                                  |   0
 .../foo/src/foo/GetterSetterExample.java      |   0
 .../foo/test/src/foo/HelloWorldTest.java      |   0
 example/javamodule/5-resources/build.sc       |  13 ++++
 .../5-resources/foo/resources/file.txt        |   1 +
 .../javamodule/5-resources/foo/src/Foo.java   |  15 ++++
 .../foo/test/other-files/other-file.txt       |   1 +
 .../foo/test/resources/test-file-a.txt        |   1 +
 .../foo/test/resources/test-file-b.txt        |   1 +
 .../5-resources/foo/test/src/FooTests.java    |  52 ++++++++++++++
 .../build.sc                                  |   0
 .../lib/nanojson-1.8.jar                      | Bin
 .../src/foo/Foo.java                          |   0
 .../{8-main-class => 9-main-class}/build.sc   |   0
 .../src/foo/Bar.java                          |   0
 .../src/foo/Foo.java                          |   0
 .../src/foo/Qux.java                          |   0
 .../build.sc                                  |   0
 .../src/Foo.scala                             |   0
 .../textfile.txt                              |   0
 .../bar/resources/application.conf            |   0
 .../build.sc                                  |   0
 .../foo/resources/application.conf            |   0
 .../foo/src/Foo.scala                         |   0
 .../build.sc                                  |   0
 .../foo/src/Foo.scala                         |   0
 .../build.sc                                  |   0
 .../src/Foo.scala                             |   0
 .../test/src/FooTests.scala                   |   0
 .../{13-unidoc => 14-unidoc}/build.sc         |   0
 .../foo/bar/src/Bar.scala                     |   0
 .../foo/qux/src/Qux.scala                     |   0
 .../foo/src/Foo.scala                         |   0
 example/scalamodule/4-test-deps/build.sc      |   1 +
 example/scalamodule/5-resources/build.sc      |  66 ++++++++++++++++++
 .../5-resources/foo/resources/file.txt        |   1 +
 .../scalamodule/5-resources/foo/src/Foo.scala |   6 ++
 .../foo/test/other-files/other-file.txt       |   1 +
 .../foo/test/resources/test-file-a.txt        |   1 +
 .../foo/test/resources/test-file-b.txt        |   1 +
 .../5-resources/foo/test/src/FooTests.scala   |  31 ++++++++
 .../build.sc                                  |   0
 .../src/Bar.scala                             |   0
 .../src/Foo.scala                             |   0
 .../{6-docjar => 7-docjar}/bar/src/Bar.scala  |   0
 .../{6-docjar => 7-docjar}/build.sc           |   0
 .../{6-docjar => 7-docjar}/foo/src/Foo.scala  |   0
 .../build.sc                                  |   0
 .../lib/nanojson-1.8.jar                      | Bin
 .../src/Foo.scala                             |   0
 .../{8-main-class => 9-main-class}/build.sc   |   0
 .../src/Bar.scala                             |   0
 .../src/Foo.scala                             |   0
 .../src/Qux.scala                             |   0
 71 files changed, 214 insertions(+), 15 deletions(-)
 rename example/javamodule/{9-downloading-non-maven-jars => 10-downloading-non-maven-jars}/build.sc (100%)
 rename example/javamodule/{9-downloading-non-maven-jars => 10-downloading-non-maven-jars}/src/foo/Foo.java (100%)
 rename example/javamodule/{9-downloading-non-maven-jars => 10-downloading-non-maven-jars}/textfile.txt (100%)
 rename example/javamodule/{10-assembly-config => 11-assembly-config}/bar/resources/application.conf (100%)
 rename example/javamodule/{10-assembly-config => 11-assembly-config}/build.sc (100%)
 rename example/javamodule/{10-assembly-config => 11-assembly-config}/foo/resources/application.conf (100%)
 rename example/javamodule/{10-assembly-config => 11-assembly-config}/foo/src/foo/Foo.java (100%)
 rename example/javamodule/{11-repository-config => 12-repository-config}/build.sc (100%)
 rename example/javamodule/{11-repository-config => 12-repository-config}/foo/src/foo/Foo.java (100%)
 rename example/javamodule/{12-jni => 13-jni}/build.sc (100%)
 rename example/javamodule/{12-jni => 13-jni}/native-src/HelloWorld.c (100%)
 rename example/javamodule/{12-jni => 13-jni}/src/foo/HelloWorld.java (100%)
 rename example/javamodule/{12-jni => 13-jni}/test/src/foo/HelloWorldTest.java (100%)
 rename example/javamodule/{13-annotation-processors-lombok => 14-annotation-processors-lombok}/bar/src/bar/GetterSetterExample.java (100%)
 rename example/javamodule/{13-annotation-processors-lombok => 14-annotation-processors-lombok}/bar/test/src/bar/HelloWorldTest.java (100%)
 rename example/javamodule/{13-annotation-processors-lombok => 14-annotation-processors-lombok}/build.sc (100%)
 rename example/javamodule/{13-annotation-processors-lombok => 14-annotation-processors-lombok}/foo/src/foo/GetterSetterExample.java (100%)
 rename example/javamodule/{13-annotation-processors-lombok => 14-annotation-processors-lombok}/foo/test/src/foo/HelloWorldTest.java (100%)
 create mode 100644 example/javamodule/5-resources/build.sc
 create mode 100644 example/javamodule/5-resources/foo/resources/file.txt
 create mode 100644 example/javamodule/5-resources/foo/src/Foo.java
 create mode 100644 example/javamodule/5-resources/foo/test/other-files/other-file.txt
 create mode 100644 example/javamodule/5-resources/foo/test/resources/test-file-a.txt
 create mode 100644 example/javamodule/5-resources/foo/test/resources/test-file-b.txt
 create mode 100644 example/javamodule/5-resources/foo/test/src/FooTests.java
 rename example/javamodule/{7-unmanaged-jars => 8-unmanaged-jars}/build.sc (100%)
 rename example/javamodule/{7-unmanaged-jars => 8-unmanaged-jars}/lib/nanojson-1.8.jar (100%)
 rename example/javamodule/{7-unmanaged-jars => 8-unmanaged-jars}/src/foo/Foo.java (100%)
 rename example/javamodule/{8-main-class => 9-main-class}/build.sc (100%)
 rename example/javamodule/{8-main-class => 9-main-class}/src/foo/Bar.java (100%)
 rename example/javamodule/{8-main-class => 9-main-class}/src/foo/Foo.java (100%)
 rename example/javamodule/{8-main-class => 9-main-class}/src/foo/Qux.java (100%)
 rename example/scalamodule/{9-downloading-non-maven-jars => 10-downloading-non-maven-jars}/build.sc (100%)
 rename example/scalamodule/{9-downloading-non-maven-jars => 10-downloading-non-maven-jars}/src/Foo.scala (100%)
 rename example/scalamodule/{9-downloading-non-maven-jars => 10-downloading-non-maven-jars}/textfile.txt (100%)
 rename example/scalamodule/{10-assembly-config => 11-assembly-config}/bar/resources/application.conf (100%)
 rename example/scalamodule/{10-assembly-config => 11-assembly-config}/build.sc (100%)
 rename example/scalamodule/{10-assembly-config => 11-assembly-config}/foo/resources/application.conf (100%)
 rename example/scalamodule/{10-assembly-config => 11-assembly-config}/foo/src/Foo.scala (100%)
 rename example/scalamodule/{11-repository-config => 12-repository-config}/build.sc (100%)
 rename example/scalamodule/{11-repository-config => 12-repository-config}/foo/src/Foo.scala (100%)
 rename example/scalamodule/{12-contrib-scoverage => 13-contrib-scoverage}/build.sc (100%)
 rename example/scalamodule/{12-contrib-scoverage => 13-contrib-scoverage}/src/Foo.scala (100%)
 rename example/scalamodule/{12-contrib-scoverage => 13-contrib-scoverage}/test/src/FooTests.scala (100%)
 rename example/scalamodule/{13-unidoc => 14-unidoc}/build.sc (100%)
 rename example/scalamodule/{13-unidoc => 14-unidoc}/foo/bar/src/Bar.scala (100%)
 rename example/scalamodule/{13-unidoc => 14-unidoc}/foo/qux/src/Qux.scala (100%)
 rename example/scalamodule/{13-unidoc => 14-unidoc}/foo/src/Foo.scala (100%)
 create mode 100644 example/scalamodule/5-resources/build.sc
 create mode 100644 example/scalamodule/5-resources/foo/resources/file.txt
 create mode 100644 example/scalamodule/5-resources/foo/src/Foo.scala
 create mode 100644 example/scalamodule/5-resources/foo/test/other-files/other-file.txt
 create mode 100644 example/scalamodule/5-resources/foo/test/resources/test-file-a.txt
 create mode 100644 example/scalamodule/5-resources/foo/test/resources/test-file-b.txt
 create mode 100644 example/scalamodule/5-resources/foo/test/src/FooTests.scala
 rename example/scalamodule/{5-scala-compiler-plugins => 6-scala-compiler-plugins}/build.sc (100%)
 rename example/scalamodule/{5-scala-compiler-plugins => 6-scala-compiler-plugins}/src/Bar.scala (100%)
 rename example/scalamodule/{5-scala-compiler-plugins => 6-scala-compiler-plugins}/src/Foo.scala (100%)
 rename example/scalamodule/{6-docjar => 7-docjar}/bar/src/Bar.scala (100%)
 rename example/scalamodule/{6-docjar => 7-docjar}/build.sc (100%)
 rename example/scalamodule/{6-docjar => 7-docjar}/foo/src/Foo.scala (100%)
 rename example/scalamodule/{7-unmanaged-jars => 8-unmanaged-jars}/build.sc (100%)
 rename example/scalamodule/{7-unmanaged-jars => 8-unmanaged-jars}/lib/nanojson-1.8.jar (100%)
 rename example/scalamodule/{7-unmanaged-jars => 8-unmanaged-jars}/src/Foo.scala (100%)
 rename example/scalamodule/{8-main-class => 9-main-class}/build.sc (100%)
 rename example/scalamodule/{8-main-class => 9-main-class}/src/Bar.scala (100%)
 rename example/scalamodule/{8-main-class => 9-main-class}/src/Foo.scala (100%)
 rename example/scalamodule/{8-main-class => 9-main-class}/src/Qux.scala (100%)

diff --git a/docs/modules/ROOT/pages/Java_Module_Config.adoc b/docs/modules/ROOT/pages/Java_Module_Config.adoc
index d37badb11e4..058e6e00132 100644
--- a/docs/modules/ROOT/pages/Java_Module_Config.adoc
+++ b/docs/modules/ROOT/pages/Java_Module_Config.adoc
@@ -30,30 +30,33 @@ include::example/javamodule/3-run-compile-deps.adoc[]
 
 include::example/javamodule/4-test-deps.adoc[]
 
+== Classpath and Filesystem Resources
+
+include::example/javamodule/5-resources.adoc[]
 
 == Javadoc Config
 
-include::example/javamodule/6-docjar.adoc[]
+include::example/javamodule/7-docjar.adoc[]
 
 == Unmanaged Jars
 
-include::example/javamodule/7-unmanaged-jars.adoc[]
+include::example/javamodule/8-unmanaged-jars.adoc[]
 
 == Specifying the Main Class
 
-include::example/javamodule/8-main-class.adoc[]
+include::example/javamodule/9-main-class.adoc[]
 
 == Downloading Non-Maven Jars
 
-include::example/javamodule/9-downloading-non-maven-jars.adoc[]
+include::example/javamodule/10-downloading-non-maven-jars.adoc[]
 
 == Customizing the Assembly
 
-include::example/javamodule/10-assembly-config.adoc[]
+include::example/javamodule/11-assembly-config.adoc[]
 
 == Repository Config
 
-include::example/javamodule/11-repository-config.adoc[]
+include::example/javamodule/12-repository-config.adoc[]
 
 === Maven Central: Blocked!
 
@@ -83,8 +86,8 @@ If you are using millw, a more permanent solution could be to set the environmen
 
 == Native C Code with JNI
 
-include::example/javamodule/12-jni.adoc[]
+include::example/javamodule/13-jni.adoc[]
 
 == Annotation Processors with Lombok
 
-include::example/javamodule/13-annotation-processors-lombok.adoc[]
+include::example/javamodule/14-annotation-processors-lombok.adoc[]
diff --git a/docs/modules/ROOT/pages/Scala_Module_Config.adoc b/docs/modules/ROOT/pages/Scala_Module_Config.adoc
index 83163b99f0b..3b1065969c8 100644
--- a/docs/modules/ROOT/pages/Scala_Module_Config.adoc
+++ b/docs/modules/ROOT/pages/Scala_Module_Config.adoc
@@ -32,33 +32,37 @@ include::example/scalamodule/3-run-compile-deps.adoc[]
 
 include::example/scalamodule/4-test-deps.adoc[]
 
+== Classpath and Filesystem Resources
+
+include::example/scalamodule/5-resources.adoc[]
+
 == Scala Compiler Plugins
 
-include::example/scalamodule/5-scala-compiler-plugins.adoc[]
+include::example/scalamodule/6-scala-compiler-plugins.adoc[]
 
 == Scaladoc Config
 
-include::example/scalamodule/6-docjar.adoc[]
+include::example/scalamodule/7-docjar.adoc[]
 
 == Unmanaged Jars
 
-include::example/scalamodule/7-unmanaged-jars.adoc[]
+include::example/scalamodule/8-unmanaged-jars.adoc[]
 
 == Specifying the Main Class
 
-include::example/scalamodule/8-main-class.adoc[]
+include::example/scalamodule/9-main-class.adoc[]
 
 == Downloading Non-Maven Jars
 
-include::example/scalamodule/9-downloading-non-maven-jars.adoc[]
+include::example/scalamodule/10-downloading-non-maven-jars.adoc[]
 
 == Customizing the Assembly
 
-include::example/scalamodule/10-assembly-config.adoc[]
+include::example/scalamodule/11-assembly-config.adoc[]
 
 == Repository Config
 
-include::example/scalamodule/11-repository-config.adoc[]
+include::example/scalamodule/12-repository-config.adoc[]
 
 == Maven Central: Blocked!
 
diff --git a/example/javamodule/9-downloading-non-maven-jars/build.sc b/example/javamodule/10-downloading-non-maven-jars/build.sc
similarity index 100%
rename from example/javamodule/9-downloading-non-maven-jars/build.sc
rename to example/javamodule/10-downloading-non-maven-jars/build.sc
diff --git a/example/javamodule/9-downloading-non-maven-jars/src/foo/Foo.java b/example/javamodule/10-downloading-non-maven-jars/src/foo/Foo.java
similarity index 100%
rename from example/javamodule/9-downloading-non-maven-jars/src/foo/Foo.java
rename to example/javamodule/10-downloading-non-maven-jars/src/foo/Foo.java
diff --git a/example/javamodule/9-downloading-non-maven-jars/textfile.txt b/example/javamodule/10-downloading-non-maven-jars/textfile.txt
similarity index 100%
rename from example/javamodule/9-downloading-non-maven-jars/textfile.txt
rename to example/javamodule/10-downloading-non-maven-jars/textfile.txt
diff --git a/example/javamodule/10-assembly-config/bar/resources/application.conf b/example/javamodule/11-assembly-config/bar/resources/application.conf
similarity index 100%
rename from example/javamodule/10-assembly-config/bar/resources/application.conf
rename to example/javamodule/11-assembly-config/bar/resources/application.conf
diff --git a/example/javamodule/10-assembly-config/build.sc b/example/javamodule/11-assembly-config/build.sc
similarity index 100%
rename from example/javamodule/10-assembly-config/build.sc
rename to example/javamodule/11-assembly-config/build.sc
diff --git a/example/javamodule/10-assembly-config/foo/resources/application.conf b/example/javamodule/11-assembly-config/foo/resources/application.conf
similarity index 100%
rename from example/javamodule/10-assembly-config/foo/resources/application.conf
rename to example/javamodule/11-assembly-config/foo/resources/application.conf
diff --git a/example/javamodule/10-assembly-config/foo/src/foo/Foo.java b/example/javamodule/11-assembly-config/foo/src/foo/Foo.java
similarity index 100%
rename from example/javamodule/10-assembly-config/foo/src/foo/Foo.java
rename to example/javamodule/11-assembly-config/foo/src/foo/Foo.java
diff --git a/example/javamodule/11-repository-config/build.sc b/example/javamodule/12-repository-config/build.sc
similarity index 100%
rename from example/javamodule/11-repository-config/build.sc
rename to example/javamodule/12-repository-config/build.sc
diff --git a/example/javamodule/11-repository-config/foo/src/foo/Foo.java b/example/javamodule/12-repository-config/foo/src/foo/Foo.java
similarity index 100%
rename from example/javamodule/11-repository-config/foo/src/foo/Foo.java
rename to example/javamodule/12-repository-config/foo/src/foo/Foo.java
diff --git a/example/javamodule/12-jni/build.sc b/example/javamodule/13-jni/build.sc
similarity index 100%
rename from example/javamodule/12-jni/build.sc
rename to example/javamodule/13-jni/build.sc
diff --git a/example/javamodule/12-jni/native-src/HelloWorld.c b/example/javamodule/13-jni/native-src/HelloWorld.c
similarity index 100%
rename from example/javamodule/12-jni/native-src/HelloWorld.c
rename to example/javamodule/13-jni/native-src/HelloWorld.c
diff --git a/example/javamodule/12-jni/src/foo/HelloWorld.java b/example/javamodule/13-jni/src/foo/HelloWorld.java
similarity index 100%
rename from example/javamodule/12-jni/src/foo/HelloWorld.java
rename to example/javamodule/13-jni/src/foo/HelloWorld.java
diff --git a/example/javamodule/12-jni/test/src/foo/HelloWorldTest.java b/example/javamodule/13-jni/test/src/foo/HelloWorldTest.java
similarity index 100%
rename from example/javamodule/12-jni/test/src/foo/HelloWorldTest.java
rename to example/javamodule/13-jni/test/src/foo/HelloWorldTest.java
diff --git a/example/javamodule/13-annotation-processors-lombok/bar/src/bar/GetterSetterExample.java b/example/javamodule/14-annotation-processors-lombok/bar/src/bar/GetterSetterExample.java
similarity index 100%
rename from example/javamodule/13-annotation-processors-lombok/bar/src/bar/GetterSetterExample.java
rename to example/javamodule/14-annotation-processors-lombok/bar/src/bar/GetterSetterExample.java
diff --git a/example/javamodule/13-annotation-processors-lombok/bar/test/src/bar/HelloWorldTest.java b/example/javamodule/14-annotation-processors-lombok/bar/test/src/bar/HelloWorldTest.java
similarity index 100%
rename from example/javamodule/13-annotation-processors-lombok/bar/test/src/bar/HelloWorldTest.java
rename to example/javamodule/14-annotation-processors-lombok/bar/test/src/bar/HelloWorldTest.java
diff --git a/example/javamodule/13-annotation-processors-lombok/build.sc b/example/javamodule/14-annotation-processors-lombok/build.sc
similarity index 100%
rename from example/javamodule/13-annotation-processors-lombok/build.sc
rename to example/javamodule/14-annotation-processors-lombok/build.sc
diff --git a/example/javamodule/13-annotation-processors-lombok/foo/src/foo/GetterSetterExample.java b/example/javamodule/14-annotation-processors-lombok/foo/src/foo/GetterSetterExample.java
similarity index 100%
rename from example/javamodule/13-annotation-processors-lombok/foo/src/foo/GetterSetterExample.java
rename to example/javamodule/14-annotation-processors-lombok/foo/src/foo/GetterSetterExample.java
diff --git a/example/javamodule/13-annotation-processors-lombok/foo/test/src/foo/HelloWorldTest.java b/example/javamodule/14-annotation-processors-lombok/foo/test/src/foo/HelloWorldTest.java
similarity index 100%
rename from example/javamodule/13-annotation-processors-lombok/foo/test/src/foo/HelloWorldTest.java
rename to example/javamodule/14-annotation-processors-lombok/foo/test/src/foo/HelloWorldTest.java
diff --git a/example/javamodule/5-resources/build.sc b/example/javamodule/5-resources/build.sc
new file mode 100644
index 00000000000..d31612440ae
--- /dev/null
+++ b/example/javamodule/5-resources/build.sc
@@ -0,0 +1,13 @@
+//// SNIPPET:BUILD
+import mill._, javalib._
+
+object foo extends JavaModule {
+  object test extends JavaTests with TestModule.Junit4 {
+    def otherFiles = T.source(millSourcePath / "other-files")
+
+    def forkEnv = super.forkEnv() ++ Map(
+      "OTHER_FILES_FOLDER" -> otherFiles().path.toString
+    )
+  }
+}
+
diff --git a/example/javamodule/5-resources/foo/resources/file.txt b/example/javamodule/5-resources/foo/resources/file.txt
new file mode 100644
index 00000000000..c3e18f6e79b
--- /dev/null
+++ b/example/javamodule/5-resources/foo/resources/file.txt
@@ -0,0 +1 @@
+Hello World Resource File
\ No newline at end of file
diff --git a/example/javamodule/5-resources/foo/src/Foo.java b/example/javamodule/5-resources/foo/src/Foo.java
new file mode 100644
index 00000000000..a57cab9c41d
--- /dev/null
+++ b/example/javamodule/5-resources/foo/src/Foo.java
@@ -0,0 +1,15 @@
+package foo;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+public class Foo {
+
+  // Read `file.txt` from classpath
+  public static String classpathResourceText() throws IOException {
+    // Get the resource as an InputStream
+    try (InputStream inputStream = Foo.class.getClassLoader().getResourceAsStream("file.txt")) {
+      return new String(inputStream.readAllBytes());
+    }
+  }
+}
\ No newline at end of file
diff --git a/example/javamodule/5-resources/foo/test/other-files/other-file.txt b/example/javamodule/5-resources/foo/test/other-files/other-file.txt
new file mode 100644
index 00000000000..194f575e5c8
--- /dev/null
+++ b/example/javamodule/5-resources/foo/test/other-files/other-file.txt
@@ -0,0 +1 @@
+Other Hello World File
\ No newline at end of file
diff --git a/example/javamodule/5-resources/foo/test/resources/test-file-a.txt b/example/javamodule/5-resources/foo/test/resources/test-file-a.txt
new file mode 100644
index 00000000000..9e67fcfe4be
--- /dev/null
+++ b/example/javamodule/5-resources/foo/test/resources/test-file-a.txt
@@ -0,0 +1 @@
+Test Hello World Resource File A
\ No newline at end of file
diff --git a/example/javamodule/5-resources/foo/test/resources/test-file-b.txt b/example/javamodule/5-resources/foo/test/resources/test-file-b.txt
new file mode 100644
index 00000000000..289e86183e8
--- /dev/null
+++ b/example/javamodule/5-resources/foo/test/resources/test-file-b.txt
@@ -0,0 +1 @@
+Test Hello World Resource File B
\ No newline at end of file
diff --git a/example/javamodule/5-resources/foo/test/src/FooTests.java b/example/javamodule/5-resources/foo/test/src/FooTests.java
new file mode 100644
index 00000000000..d8f837dae32
--- /dev/null
+++ b/example/javamodule/5-resources/foo/test/src/FooTests.java
@@ -0,0 +1,52 @@
+package foo;
+
+import org.junit.Test;
+import static org.junit.Assert.*;
+
+import java.io.InputStream;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.ArrayList;
+
+public class FooTests {
+
+  @Test
+  public void simple() throws IOException {
+    // Reference app module's `Foo` class which reads `file.txt` from classpath
+    String appClasspathResourceText = Foo.classpathResourceText();
+    assertEquals("Hello World Resource File", appClasspathResourceText);
+
+    // Read `test-file-a.txt` from classpath
+    String testClasspathResourceText;
+    try (InputStream inputStream = Foo.class.getClassLoader().getResourceAsStream("test-file-a.txt")) {
+      testClasspathResourceText = new String(inputStream.readAllBytes());
+    }
+    assertEquals("Test Hello World Resource File A", testClasspathResourceText);
+
+    // Use `MILL_TEST_RESOURCE_FOLDER` to read `test-file-b.txt` from filesystem
+    Path testFileResourceDir = Paths.get(System.getenv("MILL_TEST_RESOURCE_FOLDER"));
+    String testFileResourceText = new String(
+            Files.readAllBytes(testFileResourceDir.resolve("test-file-b.txt"))
+    );
+    assertEquals("Test Hello World Resource File B", testFileResourceText);
+
+    // Use `MILL_TEST_RESOURCE_FOLDER` to list files available in resource folder
+    List<Path> actualFiles = new ArrayList<>(Files.list(testFileResourceDir).toList());
+    actualFiles.sort(Path::compareTo);
+    List<Path> expectedFiles = List.of(
+            testFileResourceDir.resolve("test-file-a.txt"),
+            testFileResourceDir.resolve("test-file-b.txt")
+    );
+    assertEquals(expectedFiles, actualFiles);
+
+    // Use the `OTHER_FILES_FOLDER` configured in your build to access the
+    // files in `foo/test/other-files/`.
+    String otherFileText = new String(
+            Files.readAllBytes(Paths.get(System.getenv("OTHER_FILES_FOLDER"), "other-file.txt"))
+    );
+    assertEquals("Other Hello World File", otherFileText);
+  }
+}
\ No newline at end of file
diff --git a/example/javamodule/7-unmanaged-jars/build.sc b/example/javamodule/8-unmanaged-jars/build.sc
similarity index 100%
rename from example/javamodule/7-unmanaged-jars/build.sc
rename to example/javamodule/8-unmanaged-jars/build.sc
diff --git a/example/javamodule/7-unmanaged-jars/lib/nanojson-1.8.jar b/example/javamodule/8-unmanaged-jars/lib/nanojson-1.8.jar
similarity index 100%
rename from example/javamodule/7-unmanaged-jars/lib/nanojson-1.8.jar
rename to example/javamodule/8-unmanaged-jars/lib/nanojson-1.8.jar
diff --git a/example/javamodule/7-unmanaged-jars/src/foo/Foo.java b/example/javamodule/8-unmanaged-jars/src/foo/Foo.java
similarity index 100%
rename from example/javamodule/7-unmanaged-jars/src/foo/Foo.java
rename to example/javamodule/8-unmanaged-jars/src/foo/Foo.java
diff --git a/example/javamodule/8-main-class/build.sc b/example/javamodule/9-main-class/build.sc
similarity index 100%
rename from example/javamodule/8-main-class/build.sc
rename to example/javamodule/9-main-class/build.sc
diff --git a/example/javamodule/8-main-class/src/foo/Bar.java b/example/javamodule/9-main-class/src/foo/Bar.java
similarity index 100%
rename from example/javamodule/8-main-class/src/foo/Bar.java
rename to example/javamodule/9-main-class/src/foo/Bar.java
diff --git a/example/javamodule/8-main-class/src/foo/Foo.java b/example/javamodule/9-main-class/src/foo/Foo.java
similarity index 100%
rename from example/javamodule/8-main-class/src/foo/Foo.java
rename to example/javamodule/9-main-class/src/foo/Foo.java
diff --git a/example/javamodule/8-main-class/src/foo/Qux.java b/example/javamodule/9-main-class/src/foo/Qux.java
similarity index 100%
rename from example/javamodule/8-main-class/src/foo/Qux.java
rename to example/javamodule/9-main-class/src/foo/Qux.java
diff --git a/example/scalamodule/9-downloading-non-maven-jars/build.sc b/example/scalamodule/10-downloading-non-maven-jars/build.sc
similarity index 100%
rename from example/scalamodule/9-downloading-non-maven-jars/build.sc
rename to example/scalamodule/10-downloading-non-maven-jars/build.sc
diff --git a/example/scalamodule/9-downloading-non-maven-jars/src/Foo.scala b/example/scalamodule/10-downloading-non-maven-jars/src/Foo.scala
similarity index 100%
rename from example/scalamodule/9-downloading-non-maven-jars/src/Foo.scala
rename to example/scalamodule/10-downloading-non-maven-jars/src/Foo.scala
diff --git a/example/scalamodule/9-downloading-non-maven-jars/textfile.txt b/example/scalamodule/10-downloading-non-maven-jars/textfile.txt
similarity index 100%
rename from example/scalamodule/9-downloading-non-maven-jars/textfile.txt
rename to example/scalamodule/10-downloading-non-maven-jars/textfile.txt
diff --git a/example/scalamodule/10-assembly-config/bar/resources/application.conf b/example/scalamodule/11-assembly-config/bar/resources/application.conf
similarity index 100%
rename from example/scalamodule/10-assembly-config/bar/resources/application.conf
rename to example/scalamodule/11-assembly-config/bar/resources/application.conf
diff --git a/example/scalamodule/10-assembly-config/build.sc b/example/scalamodule/11-assembly-config/build.sc
similarity index 100%
rename from example/scalamodule/10-assembly-config/build.sc
rename to example/scalamodule/11-assembly-config/build.sc
diff --git a/example/scalamodule/10-assembly-config/foo/resources/application.conf b/example/scalamodule/11-assembly-config/foo/resources/application.conf
similarity index 100%
rename from example/scalamodule/10-assembly-config/foo/resources/application.conf
rename to example/scalamodule/11-assembly-config/foo/resources/application.conf
diff --git a/example/scalamodule/10-assembly-config/foo/src/Foo.scala b/example/scalamodule/11-assembly-config/foo/src/Foo.scala
similarity index 100%
rename from example/scalamodule/10-assembly-config/foo/src/Foo.scala
rename to example/scalamodule/11-assembly-config/foo/src/Foo.scala
diff --git a/example/scalamodule/11-repository-config/build.sc b/example/scalamodule/12-repository-config/build.sc
similarity index 100%
rename from example/scalamodule/11-repository-config/build.sc
rename to example/scalamodule/12-repository-config/build.sc
diff --git a/example/scalamodule/11-repository-config/foo/src/Foo.scala b/example/scalamodule/12-repository-config/foo/src/Foo.scala
similarity index 100%
rename from example/scalamodule/11-repository-config/foo/src/Foo.scala
rename to example/scalamodule/12-repository-config/foo/src/Foo.scala
diff --git a/example/scalamodule/12-contrib-scoverage/build.sc b/example/scalamodule/13-contrib-scoverage/build.sc
similarity index 100%
rename from example/scalamodule/12-contrib-scoverage/build.sc
rename to example/scalamodule/13-contrib-scoverage/build.sc
diff --git a/example/scalamodule/12-contrib-scoverage/src/Foo.scala b/example/scalamodule/13-contrib-scoverage/src/Foo.scala
similarity index 100%
rename from example/scalamodule/12-contrib-scoverage/src/Foo.scala
rename to example/scalamodule/13-contrib-scoverage/src/Foo.scala
diff --git a/example/scalamodule/12-contrib-scoverage/test/src/FooTests.scala b/example/scalamodule/13-contrib-scoverage/test/src/FooTests.scala
similarity index 100%
rename from example/scalamodule/12-contrib-scoverage/test/src/FooTests.scala
rename to example/scalamodule/13-contrib-scoverage/test/src/FooTests.scala
diff --git a/example/scalamodule/13-unidoc/build.sc b/example/scalamodule/14-unidoc/build.sc
similarity index 100%
rename from example/scalamodule/13-unidoc/build.sc
rename to example/scalamodule/14-unidoc/build.sc
diff --git a/example/scalamodule/13-unidoc/foo/bar/src/Bar.scala b/example/scalamodule/14-unidoc/foo/bar/src/Bar.scala
similarity index 100%
rename from example/scalamodule/13-unidoc/foo/bar/src/Bar.scala
rename to example/scalamodule/14-unidoc/foo/bar/src/Bar.scala
diff --git a/example/scalamodule/13-unidoc/foo/qux/src/Qux.scala b/example/scalamodule/14-unidoc/foo/qux/src/Qux.scala
similarity index 100%
rename from example/scalamodule/13-unidoc/foo/qux/src/Qux.scala
rename to example/scalamodule/14-unidoc/foo/qux/src/Qux.scala
diff --git a/example/scalamodule/13-unidoc/foo/src/Foo.scala b/example/scalamodule/14-unidoc/foo/src/Foo.scala
similarity index 100%
rename from example/scalamodule/13-unidoc/foo/src/Foo.scala
rename to example/scalamodule/14-unidoc/foo/src/Foo.scala
diff --git a/example/scalamodule/4-test-deps/build.sc b/example/scalamodule/4-test-deps/build.sc
index 6332591d476..5607088a025 100644
--- a/example/scalamodule/4-test-deps/build.sc
+++ b/example/scalamodule/4-test-deps/build.sc
@@ -54,3 +54,4 @@ Using BazTestUtils.bazAssertEquals
 ...
 
 */
+
diff --git a/example/scalamodule/5-resources/build.sc b/example/scalamodule/5-resources/build.sc
new file mode 100644
index 00000000000..eefb26e51d3
--- /dev/null
+++ b/example/scalamodule/5-resources/build.sc
@@ -0,0 +1,66 @@
+//// SNIPPET:BUILD
+import mill._, scalalib._
+
+object foo extends ScalaModule {
+  def scalaVersion = "2.13.8"
+  def ivyDeps = Agg(
+    ivy"com.lihaoyi::os-lib:0.9.1"
+  )
+
+  object test extends ScalaTests {
+    def ivyDeps = Agg(ivy"com.lihaoyi::utest:0.8.4")
+    def testFramework = "utest.runner.Framework"
+
+    def otherFiles = T.source(millSourcePath / "other-files")
+
+    def forkEnv = super.forkEnv() ++ Map(
+      "OTHER_FILES_FOLDER" -> otherFiles().path.toString
+    )
+  }
+}
+//// SNIPPET:END
+
+/** Usage
+
+> ./mill foo.test
+... foo.FooTests.simple ...
+...
+
+*/
+
+// This section discusses how tests can depend on resources locally on disk.
+// Mill provides two ways to do this: via the JVM classpath resources, and via
+// the resource folder which is made available as the environment variable
+// `TEST_MILL_RESOURCE_FOLDER`;
+//
+// * The *classpath resources* are useful when you want to fetch individual files,
+//   and are bundled with the application by the `.assembly` step when constructing
+//   an assembly jar for deployment. But they do not allow you to list folders
+//   or perform other filesystem operations.
+//
+// * The *resource folder*, available via `TEST_MILL_RESOURCE_FOLDER`, gives you
+//   access to the folder path of the resources on disk. This is useful in allowing
+//   you to list and otherwise manipulate the filesystem, which you cannot do with
+//   *classpath resources*. However, the `TEST_MILL_RESOURCE_FOLDER` only exists
+//   when running tests using Mill, and is not available when executing applications
+//   packaged for deployment via `.assembly`
+//
+// * Apart from `resources/`, you can provide additional folders to your test suite
+//   by defining a `T.source` (`otherFiles` above) and passing it to `forkEnv`. This
+//   provide the folder path as an environment variable that the test can make use of
+//
+// Note that tests require that you pass in any files that they depend on explicitly.
+// This is necessary so that Mill knows when a test needs to be re-run and when a
+// previous result can be cached. This also ensures that tests reading and writing
+// to the current working directory do not accidentally interfere with each others
+// files, especially when running in parallel.
+//
+// The test process runs in a `sandbox/` folder, not in your project root folder, to
+// prevent you from accidentally accessing files without explicitly passing them. If
+// you have legacy tests that need to run in the project root folder to work, you
+// can configure your test suite with `def testSandboxWorkingDir = false` to disable
+// the sandbox and make the tests run in the project root.
+
+
+
+
diff --git a/example/scalamodule/5-resources/foo/resources/file.txt b/example/scalamodule/5-resources/foo/resources/file.txt
new file mode 100644
index 00000000000..c3e18f6e79b
--- /dev/null
+++ b/example/scalamodule/5-resources/foo/resources/file.txt
@@ -0,0 +1 @@
+Hello World Resource File
\ No newline at end of file
diff --git a/example/scalamodule/5-resources/foo/src/Foo.scala b/example/scalamodule/5-resources/foo/src/Foo.scala
new file mode 100644
index 00000000000..7000e1b1494
--- /dev/null
+++ b/example/scalamodule/5-resources/foo/src/Foo.scala
@@ -0,0 +1,6 @@
+package foo
+
+object Foo {
+  // Read `file.txt` from classpath
+  def classpathResourceText = os.read(os.resource / "file.txt")
+}
diff --git a/example/scalamodule/5-resources/foo/test/other-files/other-file.txt b/example/scalamodule/5-resources/foo/test/other-files/other-file.txt
new file mode 100644
index 00000000000..194f575e5c8
--- /dev/null
+++ b/example/scalamodule/5-resources/foo/test/other-files/other-file.txt
@@ -0,0 +1 @@
+Other Hello World File
\ No newline at end of file
diff --git a/example/scalamodule/5-resources/foo/test/resources/test-file-a.txt b/example/scalamodule/5-resources/foo/test/resources/test-file-a.txt
new file mode 100644
index 00000000000..9e67fcfe4be
--- /dev/null
+++ b/example/scalamodule/5-resources/foo/test/resources/test-file-a.txt
@@ -0,0 +1 @@
+Test Hello World Resource File A
\ No newline at end of file
diff --git a/example/scalamodule/5-resources/foo/test/resources/test-file-b.txt b/example/scalamodule/5-resources/foo/test/resources/test-file-b.txt
new file mode 100644
index 00000000000..289e86183e8
--- /dev/null
+++ b/example/scalamodule/5-resources/foo/test/resources/test-file-b.txt
@@ -0,0 +1 @@
+Test Hello World Resource File B
\ No newline at end of file
diff --git a/example/scalamodule/5-resources/foo/test/src/FooTests.scala b/example/scalamodule/5-resources/foo/test/src/FooTests.scala
new file mode 100644
index 00000000000..81fcf07b561
--- /dev/null
+++ b/example/scalamodule/5-resources/foo/test/src/FooTests.scala
@@ -0,0 +1,31 @@
+package foo
+import utest._
+object FooTests extends TestSuite {
+  def tests = Tests {
+    test("simple") {
+      // Reference app module's `Foo` class which reads `file.txt` from classpath
+      val appClasspathResourceText = Foo.classpathResourceText
+      assert(appClasspathResourceText == "Hello World Resource File")
+
+      // Read `test-file-a.txt` from classpath
+      val testClasspathResourceText = os.read(os.resource / "test-file-a.txt")
+      assert(testClasspathResourceText == "Test Hello World Resource File A")
+
+      // Use `MILL_TEST_RESOURCE_FOLDER` to read `test-file-b.txt` from filesystem
+      val testFileResourceDir = os.Path(sys.env("MILL_TEST_RESOURCE_FOLDER"))
+      val testFileResourceText = os.read(testFileResourceDir / "test-file-b.txt")
+      assert(testFileResourceText == "Test Hello World Resource File B")
+
+      // Use `MILL_TEST_RESOURCE_FOLDER` to list files available in resource folder
+      assert(
+        os.list(testFileResourceDir).sorted ==
+        Seq(testFileResourceDir / "test-file-a.txt", testFileResourceDir / "test-file-b.txt")
+      )
+
+      // Use the `OTHER_FILES_FOLDER` configured in your build to access the
+      // files in `foo/test/other-files/`.
+      val otherFileText = os.read(os.Path(sys.env("OTHER_FILES_FOLDER")) / "other-file.txt")
+      assert(otherFileText == "Other Hello World File")
+    }
+  }
+}
diff --git a/example/scalamodule/5-scala-compiler-plugins/build.sc b/example/scalamodule/6-scala-compiler-plugins/build.sc
similarity index 100%
rename from example/scalamodule/5-scala-compiler-plugins/build.sc
rename to example/scalamodule/6-scala-compiler-plugins/build.sc
diff --git a/example/scalamodule/5-scala-compiler-plugins/src/Bar.scala b/example/scalamodule/6-scala-compiler-plugins/src/Bar.scala
similarity index 100%
rename from example/scalamodule/5-scala-compiler-plugins/src/Bar.scala
rename to example/scalamodule/6-scala-compiler-plugins/src/Bar.scala
diff --git a/example/scalamodule/5-scala-compiler-plugins/src/Foo.scala b/example/scalamodule/6-scala-compiler-plugins/src/Foo.scala
similarity index 100%
rename from example/scalamodule/5-scala-compiler-plugins/src/Foo.scala
rename to example/scalamodule/6-scala-compiler-plugins/src/Foo.scala
diff --git a/example/scalamodule/6-docjar/bar/src/Bar.scala b/example/scalamodule/7-docjar/bar/src/Bar.scala
similarity index 100%
rename from example/scalamodule/6-docjar/bar/src/Bar.scala
rename to example/scalamodule/7-docjar/bar/src/Bar.scala
diff --git a/example/scalamodule/6-docjar/build.sc b/example/scalamodule/7-docjar/build.sc
similarity index 100%
rename from example/scalamodule/6-docjar/build.sc
rename to example/scalamodule/7-docjar/build.sc
diff --git a/example/scalamodule/6-docjar/foo/src/Foo.scala b/example/scalamodule/7-docjar/foo/src/Foo.scala
similarity index 100%
rename from example/scalamodule/6-docjar/foo/src/Foo.scala
rename to example/scalamodule/7-docjar/foo/src/Foo.scala
diff --git a/example/scalamodule/7-unmanaged-jars/build.sc b/example/scalamodule/8-unmanaged-jars/build.sc
similarity index 100%
rename from example/scalamodule/7-unmanaged-jars/build.sc
rename to example/scalamodule/8-unmanaged-jars/build.sc
diff --git a/example/scalamodule/7-unmanaged-jars/lib/nanojson-1.8.jar b/example/scalamodule/8-unmanaged-jars/lib/nanojson-1.8.jar
similarity index 100%
rename from example/scalamodule/7-unmanaged-jars/lib/nanojson-1.8.jar
rename to example/scalamodule/8-unmanaged-jars/lib/nanojson-1.8.jar
diff --git a/example/scalamodule/7-unmanaged-jars/src/Foo.scala b/example/scalamodule/8-unmanaged-jars/src/Foo.scala
similarity index 100%
rename from example/scalamodule/7-unmanaged-jars/src/Foo.scala
rename to example/scalamodule/8-unmanaged-jars/src/Foo.scala
diff --git a/example/scalamodule/8-main-class/build.sc b/example/scalamodule/9-main-class/build.sc
similarity index 100%
rename from example/scalamodule/8-main-class/build.sc
rename to example/scalamodule/9-main-class/build.sc
diff --git a/example/scalamodule/8-main-class/src/Bar.scala b/example/scalamodule/9-main-class/src/Bar.scala
similarity index 100%
rename from example/scalamodule/8-main-class/src/Bar.scala
rename to example/scalamodule/9-main-class/src/Bar.scala
diff --git a/example/scalamodule/8-main-class/src/Foo.scala b/example/scalamodule/9-main-class/src/Foo.scala
similarity index 100%
rename from example/scalamodule/8-main-class/src/Foo.scala
rename to example/scalamodule/9-main-class/src/Foo.scala
diff --git a/example/scalamodule/8-main-class/src/Qux.scala b/example/scalamodule/9-main-class/src/Qux.scala
similarity index 100%
rename from example/scalamodule/8-main-class/src/Qux.scala
rename to example/scalamodule/9-main-class/src/Qux.scala

From dc7c8c0858a2d721daab0488ffa527642d3cec09 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Sat, 10 Aug 2024 16:42:30 -0700
Subject: [PATCH 12/13] .

---
 example/scalamodule/5-resources/build.sc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/example/scalamodule/5-resources/build.sc b/example/scalamodule/5-resources/build.sc
index eefb26e51d3..5f253dbf3d8 100644
--- a/example/scalamodule/5-resources/build.sc
+++ b/example/scalamodule/5-resources/build.sc
@@ -49,6 +49,9 @@ object foo extends ScalaModule {
 //   by defining a `T.source` (`otherFiles` above) and passing it to `forkEnv`. This
 //   provide the folder path as an environment variable that the test can make use of
 //
+// You can click the *browse* button in the above example to see an example of code
+// the uses these three approaches to load files as part of a test module.
+//
 // Note that tests require that you pass in any files that they depend on explicitly.
 // This is necessary so that Mill knows when a test needs to be re-run and when a
 // previous result can be cached. This also ensures that tests reading and writing

From 6f1b271ba591717b40b4a3ee464f210ee34f5e85 Mon Sep 17 00:00:00 2001
From: Your Name <haoyi.sg@gmail.com>
Date: Sat, 10 Aug 2024 16:50:54 -0700
Subject: [PATCH 13/13] .

---
 build.sc                                      | 20 ++++++++++++-------
 .../ROOT/pages/Java_Module_Config.adoc        |  7 ++++---
 .../ROOT/pages/Scala_Module_Config.adoc       |  4 ++--
 .../bar/src/bar/GetterSetterExample.java      |  0
 .../bar/test/src/bar/HelloWorldTest.java      |  0
 .../build.sc                                  |  0
 .../foo/src/foo/GetterSetterExample.java      |  0
 .../foo/test/src/foo/HelloWorldTest.java      |  0
 .../{6-docjar => 7-docjar}/build.sc           |  0
 .../foo/src/foo/Foo.java                      |  0
 readme.adoc                                   | 16 +++++++++++++++
 11 files changed, 35 insertions(+), 12 deletions(-)
 rename example/javamodule/{14-annotation-processors-lombok => 6-annotation-processors}/bar/src/bar/GetterSetterExample.java (100%)
 rename example/javamodule/{14-annotation-processors-lombok => 6-annotation-processors}/bar/test/src/bar/HelloWorldTest.java (100%)
 rename example/javamodule/{14-annotation-processors-lombok => 6-annotation-processors}/build.sc (100%)
 rename example/javamodule/{14-annotation-processors-lombok => 6-annotation-processors}/foo/src/foo/GetterSetterExample.java (100%)
 rename example/javamodule/{14-annotation-processors-lombok => 6-annotation-processors}/foo/test/src/foo/HelloWorldTest.java (100%)
 rename example/javamodule/{6-docjar => 7-docjar}/build.sc (100%)
 rename example/javamodule/{6-docjar => 7-docjar}/foo/src/foo/Foo.java (100%)

diff --git a/build.sc b/build.sc
index 2301c077b8c..ba4bbecc37d 100644
--- a/build.sc
+++ b/build.sc
@@ -39,15 +39,15 @@ object Settings {
   val docBranches = Seq()
   // the exact tags containing a doc root
   val legacyDocTags: Seq[String] = Seq(
-    "0.9.12",
-    "0.10.0",
-    "0.10.12",
-    "0.10.15",
-    "0.11.0-M7"
+//    "0.9.12",
+//    "0.10.0",
+//    "0.10.12",
+//    "0.10.15",
+//    "0.11.0-M7"
   )
   val docTags: Seq[String] = Seq(
-    "0.11.10",
-    "0.11.11"
+//    "0.11.10",
+//    "0.11.11"
   )
   val mimaBaseVersions: Seq[String] = 0.to(11).map("0.11." + _)
 }
@@ -1898,6 +1898,12 @@ object docs extends Module {
       s"You can browse the local pages at: ${(pages.path / "index.html").toNIO.toUri()}"
     )
   }
+  def fastPages = T {
+    val pages = generatePages(authorMode = true)().apply(Nil)
+    T.log.outputStream.println(
+      s"You can browse the local pages at: ${(pages.path / "index.html").toNIO.toUri()}"
+    )
+  }
 
   def generatePages(authorMode: Boolean) = T.task { extraSources: Seq[os.Path] =>
     T.log.errorStream.println("Creating Antora playbook ...")
diff --git a/docs/modules/ROOT/pages/Java_Module_Config.adoc b/docs/modules/ROOT/pages/Java_Module_Config.adoc
index 058e6e00132..657fce995c3 100644
--- a/docs/modules/ROOT/pages/Java_Module_Config.adoc
+++ b/docs/modules/ROOT/pages/Java_Module_Config.adoc
@@ -34,6 +34,10 @@ include::example/javamodule/4-test-deps.adoc[]
 
 include::example/javamodule/5-resources.adoc[]
 
+== Annotation Processors
+
+include::example/javamodule/6-annotation-processors.adoc[]
+
 == Javadoc Config
 
 include::example/javamodule/7-docjar.adoc[]
@@ -88,6 +92,3 @@ If you are using millw, a more permanent solution could be to set the environmen
 
 include::example/javamodule/13-jni.adoc[]
 
-== Annotation Processors with Lombok
-
-include::example/javamodule/14-annotation-processors-lombok.adoc[]
diff --git a/docs/modules/ROOT/pages/Scala_Module_Config.adoc b/docs/modules/ROOT/pages/Scala_Module_Config.adoc
index 3b1065969c8..0537a31888d 100644
--- a/docs/modules/ROOT/pages/Scala_Module_Config.adoc
+++ b/docs/modules/ROOT/pages/Scala_Module_Config.adoc
@@ -90,11 +90,11 @@ If you are using millw, a more permanent solution could be to set the environmen
 
 == Scoverage
 
-include::example/scalamodule/12-contrib-scoverage.adoc[]
+include::example/scalamodule/13-contrib-scoverage.adoc[]
 
 == Unidoc
 
-include::example/scalamodule/13-unidoc.adoc[]
+include::example/scalamodule/14-unidoc.adoc[]
 
 == Reformatting your code
 
diff --git a/example/javamodule/14-annotation-processors-lombok/bar/src/bar/GetterSetterExample.java b/example/javamodule/6-annotation-processors/bar/src/bar/GetterSetterExample.java
similarity index 100%
rename from example/javamodule/14-annotation-processors-lombok/bar/src/bar/GetterSetterExample.java
rename to example/javamodule/6-annotation-processors/bar/src/bar/GetterSetterExample.java
diff --git a/example/javamodule/14-annotation-processors-lombok/bar/test/src/bar/HelloWorldTest.java b/example/javamodule/6-annotation-processors/bar/test/src/bar/HelloWorldTest.java
similarity index 100%
rename from example/javamodule/14-annotation-processors-lombok/bar/test/src/bar/HelloWorldTest.java
rename to example/javamodule/6-annotation-processors/bar/test/src/bar/HelloWorldTest.java
diff --git a/example/javamodule/14-annotation-processors-lombok/build.sc b/example/javamodule/6-annotation-processors/build.sc
similarity index 100%
rename from example/javamodule/14-annotation-processors-lombok/build.sc
rename to example/javamodule/6-annotation-processors/build.sc
diff --git a/example/javamodule/14-annotation-processors-lombok/foo/src/foo/GetterSetterExample.java b/example/javamodule/6-annotation-processors/foo/src/foo/GetterSetterExample.java
similarity index 100%
rename from example/javamodule/14-annotation-processors-lombok/foo/src/foo/GetterSetterExample.java
rename to example/javamodule/6-annotation-processors/foo/src/foo/GetterSetterExample.java
diff --git a/example/javamodule/14-annotation-processors-lombok/foo/test/src/foo/HelloWorldTest.java b/example/javamodule/6-annotation-processors/foo/test/src/foo/HelloWorldTest.java
similarity index 100%
rename from example/javamodule/14-annotation-processors-lombok/foo/test/src/foo/HelloWorldTest.java
rename to example/javamodule/6-annotation-processors/foo/test/src/foo/HelloWorldTest.java
diff --git a/example/javamodule/6-docjar/build.sc b/example/javamodule/7-docjar/build.sc
similarity index 100%
rename from example/javamodule/6-docjar/build.sc
rename to example/javamodule/7-docjar/build.sc
diff --git a/example/javamodule/6-docjar/foo/src/foo/Foo.java b/example/javamodule/7-docjar/foo/src/foo/Foo.java
similarity index 100%
rename from example/javamodule/6-docjar/foo/src/foo/Foo.java
rename to example/javamodule/7-docjar/foo/src/foo/Foo.java
diff --git a/readme.adoc b/readme.adoc
index e8b2b3d7211..8a4fc025778 100644
--- a/readme.adoc
+++ b/readme.adoc
@@ -198,6 +198,22 @@ $ ./mill installLocal --binFile /tmp/mill --ivyRepo /tmp/millRepo
 ...
 Published 44 modules and installed /tmp/mill
 ----
+=== Testing Documentation Changes
+
+For testing documentation changes locally, you can generate documentation for the current checkout via
+
+[source,bash]
+----
+$ ./mill docs.fastPages
+----
+
+To generate documentation for both the current checkout and earlier versions, you can use
+
+
+[source,bash]
+----
+$ ./mill docs.localPages
+----
 
 === Troubleshooting