Improve deprecation UX for watchSources (#9247)

main/src/main/scala/sbt/Defaults.scala

@@ -333,7 +333,8 @@ object Defaults extends BuildCommon with DefExtra {
         new AppenderSupplier:
           def apply(s: ScopedKey[?]): Seq[Appender] = Nil
       },
-      watchSources :== Nil, // Although this is deprecated, it can't be removed or it breaks += for legacy builds.
+      // Although this is deprecated, it can't be removed or it breaks += for legacy builds.
+      ((watchSources :== Nil): @nowarn("cat=deprecation")),
       skip :== false,
       taskTemporaryDirectory := {
         val base = BuildPaths.globalTaskDirectoryStandard(appConfiguration.value.baseDirectory)

main/src/main/scala/sbt/Keys.scala

@@ -138,6 +138,11 @@ object Keys {
   val watchService = settingKey[() => WatchService]("Service to use to monitor file system changes.").withRank(BMinusSetting).withRank(DSetting)
 
   // Deprecated watch apis
+  @transient
+  @deprecated(
+    "watchSources is deprecated; use fileInputs for task inputs or watchTriggers for extra continuous-build triggers.",
+    "2.0.0"
+  )
   val watchSources = taskKey[Seq[Watched.WatchSource]]("Defines the sources in this project for continuous execution to watch for changes.").withRank(BMinusSetting)
 
   // Path Keys

main/src/main/scala/sbt/internal/WatchTransitiveDependencies.scala

@@ -21,7 +21,7 @@ import sbt.nio.FileStamper
 import sbt.nio.Keys.*
 import sbt.nio.file.Glob
 
-import scala.annotation.tailrec
+import scala.annotation.{ nowarn, tailrec }
 
 private[sbt] object WatchTransitiveDependencies {
   extension (source: Source) {
@@ -157,7 +157,7 @@ private[sbt] object WatchTransitiveDependencies {
       data.scopes.toSeq
         .withFilter(s => s == Scope.Global || s.project.toOption.exists(projects.contains))
         .flatMap { s =>
-          data.getDirect(ScopedKey(s, Keys.watchSources.key)).map { task =>
+          data.getDirect(legacyWatchSourcesScopedKey(s)).map { task =>
             task.work match
               case a: Action.Pure[Seq[Watched.WatchSource]] => Right(a.f().map(_.toGlob))
               case _                                        => Left(s)
@@ -167,11 +167,22 @@ private[sbt] object WatchTransitiveDependencies {
       DynamicInput(glob, FileStamper.LastModified, forceTrigger = true)
     scopes.flatMap {
       case Left(scope) =>
-        extracted.runTask(scope / Keys.watchSources, state)._2.map(s => toDynamicInput(s.toGlob))
+        extracted
+          .runTask(legacyWatchSourcesTask(scope), state)
+          ._2
+          .map(s => toDynamicInput(s.toGlob))
       case Right(globs) => globs.map(toDynamicInput)
     }
   }
 
+  private def legacyWatchSourcesScopedKey(
+      scope: Scope
+  ): ScopedKey[Task[Seq[Watched.WatchSource]]] =
+    (ScopedKey(scope, Keys.watchSources.key): @nowarn("cat=deprecation"))
+
+  private def legacyWatchSourcesTask(scope: Scope): TaskKey[Seq[Watched.WatchSource]] =
+    (scope / Keys.watchSources: @nowarn("cat=deprecation"))
+
   @tailrec
   private def collectKeys(
       arguments: Arguments,

sbt-app/src/sbt-test/watch/watch-sources-file-output/build.sbt

@@ -0,0 +1 @@
+watchSources += file("foo")

sbt-app/src/sbt-test/watch/watch-sources-file-output/test

@@ -0,0 +1 @@
+> show watchSources