From 7b333622459982159364ce0401638b72668ab917 Mon Sep 17 00:00:00 2001
From: MkDev11 <jaysmth689@gmail.com>
Date: Wed, 14 Jan 2026 00:57:42 -0500
Subject: [PATCH] [2.x] fix: Preserve user-defined scalacOptions in doc task
 scope (#8528)

Fixes #7482
---
 main/src/main/scala/sbt/Defaults.scala                | 11 +++--------
 .../src/sbt-test/actions/doc-scalac-options/build.sbt |  9 +++++++++
 sbt-app/src/sbt-test/actions/doc-scalac-options/test  |  3 +++
 3 files changed, 15 insertions(+), 8 deletions(-)
 create mode 100644 sbt-app/src/sbt-test/actions/doc-scalac-options/build.sbt
 create mode 100644 sbt-app/src/sbt-test/actions/doc-scalac-options/test

diff --git a/main/src/main/scala/sbt/Defaults.scala b/main/src/main/scala/sbt/Defaults.scala
index 32765391d..64a514500 100644
--- a/main/src/main/scala/sbt/Defaults.scala
+++ b/main/src/main/scala/sbt/Defaults.scala
@@ -1992,19 +1992,14 @@ object Defaults extends BuildCommon {
           else Map.empty[HashedVirtualFileRef, URI]
         },
         fileInputOptions := Seq("-doc-root-content", "-diagrams-dot-path"),
-        scalacOptions := {
-          val compileOptions = scalacOptions.value
+        scalacOptions ++= {
           val sv = scalaVersion.value
           val config = configuration.value
           val projectName = name.value
           if (ScalaArtifacts.isScala3(sv)) {
             val project = if (config == Compile) projectName else s"$projectName-$config"
-            if (scalaVersion.value.startsWith("3.0.0")) {
-              Seq("-project", project)
-            } else {
-              compileOptions ++ Seq("-project", project)
-            }
-          } else compileOptions
+            Seq("-project", project)
+          } else Seq.empty
         },
         (TaskZero / key) := Def.uncached {
           val s = streams.value
diff --git a/sbt-app/src/sbt-test/actions/doc-scalac-options/build.sbt b/sbt-app/src/sbt-test/actions/doc-scalac-options/build.sbt
new file mode 100644
index 000000000..e8ea522b7
--- /dev/null
+++ b/sbt-app/src/sbt-test/actions/doc-scalac-options/build.sbt
@@ -0,0 +1,9 @@
+lazy val root = (project in file("."))
+  .settings(
+    scalaVersion := "2.13.12",
+    Compile / doc / scalacOptions += "-no-link-warnings",
+    TaskKey[Unit]("checkDocOptions") := {
+      val opts = (Compile / doc / scalacOptions).value
+      assert(opts.contains("-no-link-warnings"), s"Expected -no-link-warnings in doc scalacOptions but got: $opts")
+    }
+  )
diff --git a/sbt-app/src/sbt-test/actions/doc-scalac-options/test b/sbt-app/src/sbt-test/actions/doc-scalac-options/test
new file mode 100644
index 000000000..22a5e9401
--- /dev/null
+++ b/sbt-app/src/sbt-test/actions/doc-scalac-options/test
@@ -0,0 +1,3 @@
+# Verify that Compile / doc / scalacOptions += works correctly
+# This tests the fix for issue #7482
+> checkDocOptions