[🐘gradle-plugin] deprecate schemaFile and sourceFolder

benchmark/app/build.gradle.kts

@@ -90,6 +90,6 @@ apollo {
     //generateCompiledField.set(false)
     addTypename.set("always")
     srcDir(generateQueries)
-    schemaFile.set(file("src/main/graphql/api/schema.graphqls"))
+    schemaFiles.from(file("src/main/graphql/api/schema.graphqls"))
   }
 }

benchmark/microbenchmark/build.gradle.kts

@@ -93,16 +93,16 @@ java {
 
 configure<com.apollographql.apollo3.gradle.api.ApolloExtension> {
   service("benchmark") {
-    sourceFolder.set("benchmark")
+    srcDir("src/main/graphql/benchmark")
     packageName.set("com.apollographql.apollo3.benchmark")
   }
   service("calendar-response") {
-    sourceFolder.set("calendar")
+    srcDir("src/main/graphql/calendar")
     codegenModels.set("responseBased")
     packageName.set("com.apollographql.apollo3.calendar.response")
   }
   service("calendar-operation") {
-    sourceFolder.set("calendar")
+    srcDir("src/main/graphql/calendar")
     codegenModels.set("operationBased")
     packageName.set("com.apollographql.apollo3.calendar.operation")
   }

docs/source/advanced/multi-modules.mdx

@@ -22,8 +22,8 @@ apollo {
     // enable generation of metadata for use by downstream modules 
     generateApolloMetadata.set(true)
 
-    // If you need to specify the location of your schema
-    schemaFile.set(/*...*/)
+    // If you need to specify the location of your schema files
+    schemaFiles.from(/*...*/)
 
     // define options that must be shared between all modules using this schema
     mapScalar(/*...*/)

docs/source/advanced/plugin-configuration.mdx

@@ -32,7 +32,7 @@ Specify the location of your schema file using the `schemaFile` property:
 ```kotlin
 apollo {
   service("service") {
-    schemaFile.set(file("shared/graphql/schema.graphqls"))
+    schemaFiles.from(file("shared/graphql/schema.graphqls"))
   }
 }
 ```
@@ -251,10 +251,10 @@ apollo {
     // Operation files to exclude.
     excludes.add("**/*.graphqls")
 
-    // explicitly set the schema
-    schemaFile.set("src/main/graphql/schema.graphqls")
-    // you can also merge different files together
-    schemaFile.setFrom("shared/graphql/schema.graphqls", "shared/graphql/extra.graphqls")
+    // Explicitly set the schema
+    schemaFiles.from("src/main/graphql/schema.graphqls")
+    // Extend your schema locally with type extensions
+    schemaFiles.from("shared/graphql/schema.graphqls", "shared/graphql/extra.graphqls")
 
     // What codegen to use. One of "operationBased", "responseBased"
     codegenModels.set("operationBased")

intellij-plugin/build.gradle.kts

@@ -231,7 +231,7 @@ fun isSnapshotBuild() = System.getenv("IJ_PLUGIN_SNAPSHOT").toBoolean()
 apollo {
   service("apolloDebug") {
     packageName.set("com.apollographql.apollo3.debug")
-    schemaFile.set(file("../libraries/apollo-debug-server/src/androidMain/resources/schema.graphqls"))
+    schemaFiles.from(file("../libraries/apollo-debug-server/src/androidMain/resources/schema.graphqls"))
     introspection {
       endpointUrl.set("http://localhost:12200/")
       schemaFile.set(file("../libraries/apollo-debug-server/src/androidMain/resources/schema.graphqls"))

libraries/apollo-gradle-plugin-external/src/main/kotlin/com/apollographql/apollo3/gradle/api/Service.kt

@@ -49,10 +49,12 @@ interface Service {
 
   /**
    * Where to look for GraphQL sources.
-   * The plugin will look in "src/main/graphql/$sourceFolder" for Android/JVM projects and "src/commonMain/graphql/$sourceFolder" for multiplatform projects.
+   * The plugin searches "src/main/graphql/$sourceFolder" for Android/JVM projects and "src/commonMain/graphql/$sourceFolder" for multiplatform projects.
    *
-   * For more control, see also [srcDir]
+   * For more control, see [srcDir]
    */
+  @Deprecated("Replace with srcDir(\"src/[main|commonMain]/graphql/\$sourceFolder\")")
+  @ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v4_0_0)
   val sourceFolder: Property<String>
 
   /**
@@ -62,23 +64,34 @@ interface Service {
    *
    * @param directory the directory where the .graphql operation files are
    * [directory] is evaluated as in [Project.file](https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#file-java.lang.Object-)
-   * Valid value include path Strings, File and RegularFileProperty
-   *
    */
   fun srcDir(directory: Any)
 
   /**
-   * A shorthand property that will be used if [schemaFiles] is empty
+   * The location of the schema file.
+   *
+   * Because clients may extend the schema with client extensions in separate files, this is deprecated
+   * in favor of [schemaFiles].
    */
+  @Deprecated("Replace with schemaFiles.from()")
+  @ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v4_0_0)
   val schemaFile: RegularFileProperty
 
   /**
-   * The schema files as either a ".json" introspection schema or a ".sdl|.graphqls" SDL schema. You might come across schemas named "schema.graphql",
-   * these are SDL schemas most of the time that need to be renamed to "schema.graphqls" to be recognized properly.
+   * The schema files in either ".json" introspection schemas or ".sdl|.graphqls" SDL schemas.
    *
-   * The compiler accepts multiple schema files in order to add extensions to specify key fields and other schema extensions.
+   * Most of the time, [schemaFiles] contains a main schema and an optional separate file for client extensions.
+   * You may set any number of files and the compiler will merge them. The merge order is:
+   * - main schema file first (the main schema file is the file that contains the schema definition or the Query type)
+   * - lexicographic order of the filename for other schema files
    *
-   * By default, the plugin collects all "schema.[json|sdl|graphqls]" file in the source roots
+   * If not set or empty, the plugin collects all "schema.[json|sdl|graphqls]" files in the [srcDir] roots.
+   *
+   * Example:
+   *
+   * ```kotlin
+   * schemaFiles.from("src/main/graphql/schema.graphqls", "src/main/graphql/extra.graphqls")
+   * ```
    */
   val schemaFiles: ConfigurableFileCollection
 

libraries/apollo-gradle-plugin-external/src/main/kotlin/com/apollographql/apollo3/gradle/internal/DefaultApolloExtension.kt

@@ -360,7 +360,11 @@ abstract class DefaultApolloExtension(
     services.add(service)
 
     if (service.graphqlSourceDirectorySet.isReallyEmpty) {
+      @Suppress("DEPRECATION")
       val sourceFolder = service.sourceFolder.getOrElse("")
+      if (sourceFolder.isNotEmpty()) {
+        project.logger.lifecycle("Apollo: using 'sourceFolder' is deprecated, please replace with 'srcDir(\"src/${project.mainSourceSet()}/graphql/$sourceFolder\")'")
+      }
       val dir = File(project.projectDir, "src/${project.mainSourceSet()}/graphql/$sourceFolder")
 
       service.graphqlSourceDirectorySet.srcDir(dir)

libraries/apollo-gradle-plugin-external/src/main/kotlin/com/apollographql/apollo3/gradle/internal/DefaultService.kt

@@ -215,7 +215,9 @@ internal fun DefaultService.fallbackFiles(project: Project, block: (Configurable
 internal fun DefaultService.schemaFiles(project: Project): FileCollection {
   val fileCollection = project.files()
 
+  @Suppress("DEPRECATION")
   if (schemaFile.isPresent) {
+    project.logger.lifecycle("Apollo: using 'schemaFile.set()' is deprecated as additional schema files like 'extra.graphqls' might be required. Please use 'schemaFiles.from()' instead.")
     fileCollection.from(schemaFile)
   } else {
     fileCollection.from(schemaFiles)

libraries/apollo-gradle-plugin/src/test-java11/kotlin/com/apollographql/apollo3/gradle/test/KotlinDSLTests.kt

@@ -38,7 +38,7 @@ class KotlinDSLTests {
           useSemanticNaming.set(false)
           mapScalar("DateTime", "java.util.Date")
           srcDir("src/main/graphql/com/example")
-          schemaFile.set(file("src/main/graphql/com/example/schema.json"))
+          schemaFiles.from(file("src/main/graphql/com/example/schema.json"))
           packageName.set("com.starwars")
           excludes.set(listOf("*.gql"))
         }

libraries/apollo-gradle-plugin/src/test-java11/kotlin/com/apollographql/apollo3/gradle/test/SchemaResolutionTests.kt

@@ -52,7 +52,7 @@ class SchemaResolutionTests {
       apollo {
         service("api") {
           packageNamesFromFilePaths()
-          schemaFile.set(file("src/main/graphql/schema.sdl"))
+          schemaFiles.from(file("src/main/graphql/schema.sdl"))
         }
       }
     """.trimIndent()

libraries/apollo-gradle-plugin/src/test-java11/kotlin/com/apollographql/apollo3/gradle/test/ServiceTests.kt

@@ -120,7 +120,7 @@ class ServiceTests {
     withSimpleProject("""
       apollo {
         service("starwars") {
-          schemaFile.set(file("${schema.absolutePath}"))
+          schemaFiles.from(file("${schema.absolutePath}"))
           packageName.set("com.example")
         }
       }

libraries/apollo-gradle-plugin/testProjects/androidVariants/build.gradle.kts

@@ -37,7 +37,7 @@ java.toolchain {
 apollo {
   createAllAndroidVariantServices(".", "example") {
     // Here we set the same schema file for all variants
-    schemaFile.set(file("src/main/graphql/com/example/schema.sdl"))
+    schemaFiles.from(file("src/main/graphql/com/example/schema.sdl"))
     packageName.set("com.example")
   }
 }

libraries/apollo-gradle-plugin/testProjects/configuration-cache/root/build.gradle.kts

@@ -11,7 +11,7 @@ apollo {
 
     introspection {
       this.endpointUrl.set("ENDPOINT")
-      this.schemaFile.set(file("schema.json"))
+      schemaFile.set(file("schema.json"))
     }
   }
 }

libraries/apollo-gradle-plugin/testProjects/kotlinJvmSourceSets/build.gradle.kts

@@ -11,6 +11,6 @@ dependencies {
 apollo {
   createAllKotlinSourceSetServices(".", "example") {
     packageNamesFromFilePaths()
-    schemaFile.set(file("src/main/graphql/com/example/schema.sdl"))
+    schemaFiles.from(file("src/main/graphql/com/example/schema.sdl"))
   }
 }

libraries/apollo-gradle-plugin/testProjects/lazy-schema-file/build.gradle.kts

@@ -20,6 +20,6 @@ val installTask = tasks.register("generateSchema", GenerateSchemaTask::class.jav
 apollo {
   service("service") {
     packageName.set("com.example")
-    schemaFile.set(installTask.flatMap { it.outputFile })
+    schemaFiles.from(installTask.flatMap { it.outputFile })
   }
 }

libraries/apollo-tooling/build.gradle.kts

@@ -30,14 +30,14 @@ apollo {
   // https://spec.graphql.org/draft/#sec-Schema-Introspection.Schema-Introspection-Schema
   service("graphql") {
     packageName.set("com.apollographql.apollo3.tooling.graphql")
-    sourceFolder.set("graphql")
+    srcDir("src/main/graphql/graphql")
     generateAsInternal.set(true)
   }
 
   // https://studio.apollographql.com/public/apollo-platform/variant/main/home
   service("platform-api-public") {
     packageName.set("com.apollographql.apollo3.tooling.platformapi.public")
-    sourceFolder.set("platform-api/public")
+    srcDir("src/main/graphql/platform-api/public")
     generateAsInternal.set(true)
     mapScalarToKotlinString("GraphQLDocument")
     registry {
@@ -51,7 +51,7 @@ apollo {
   // https://studio-staging.apollographql.com/graph/engine/variant/prod/home
   service("platform-api-internal") {
     packageName.set("com.apollographql.apollo3.tooling.platformapi.internal")
-    sourceFolder.set("platform-api/internal")
+    srcDir("src/main/graphql/platform-api/internal")
     generateAsInternal.set(true)
     introspection {
       endpointUrl.set("https://graphql.api.apollographql.com/api/graphql")

tests/defer/build.gradle.kts

@@ -49,12 +49,12 @@ fun configureApollo(generateKotlinModels: Boolean) {
     service("base-$extra") {
       packageName.set("defer")
       this.generateKotlinModels.set(generateKotlinModels)
-      sourceFolder.set("base")
+      srcDir("src/commonMain/graphql/base")
       configureConnection(generateKotlinModels)
     }
     service("supergraph-$extra") {
       packageName.set("supergraph")
-      sourceFolder.set("supergraph")
+      srcDir("src/commonMain/graphql/supergraph")
       this.addTypename.set("ifAbstract")
       this.generateKotlinModels.set(generateKotlinModels)
       configureConnection(generateKotlinModels)

tests/java-client/build.gradle.kts

@@ -16,7 +16,7 @@ dependencies {
 
 apollo {
   service("main") {
-    schemaFile.set(file("../sample-server/src/main/resources/schema.graphqls"))
+    schemaFiles.from(file("../sample-server/src/main/resources/schema.graphqls"))
     srcDir("src/main/graphql/main")
     packageName.set("javatest")
     generateModelBuilders.set(true)

tests/multipart/build.gradle.kts

@@ -24,11 +24,11 @@ kotlin {
 
 apollo {
   service("mockserver") {
-    sourceFolder.set("mockserver")
+    srcDir("src/commonMain/graphql/mockserver")
     packageName.set("multipart")
   }
   service("router") {
-    sourceFolder.set("router")
+    srcDir("src/commonMain/graphql/router")
     packageName.set("router")
   }
 }

tests/no-runtime/build.gradle.kts

@@ -17,6 +17,6 @@ dependencies {
 apollo {
   service("service") {
     packageName.set("com.example")
-    schemaFile.set(file("../sample-server/src/main/resources/schema.graphqls"))
+    schemaFiles.from(file("../sample-server/src/main/resources/schema.graphqls"))
   }
 }

tests/normalization-tests/build.gradle.kts

@@ -16,11 +16,11 @@ dependencies {
 
 apollo {
   service("1") {
-    sourceFolder.set("1")
+    srcDir("src/main/graphql/1")
     packageName.set("com.example.one")
   }
   service("2") {
-    sourceFolder.set("2")
+    srcDir("src/main/graphql/2")
     packageName.set("com.example.two")
   }
   service("3") {

tests/pagination/build.gradle.kts

@@ -29,27 +29,27 @@ kotlin {
 apollo {
   service("embed") {
     packageName.set("embed")
-    sourceFolder.set("embed")
+    srcDir("src/commonMain/graphql/embed")
   }
 
   service("pagination.offsetBasedWithArray") {
     packageName.set("pagination.offsetBasedWithArray")
-    sourceFolder.set("pagination/offsetBasedWithArray")
+    srcDir("src/commonMain/graphql/pagination/offsetBasedWithArray")
     generateDataBuilders.set(true)
   }
   service("pagination.offsetBasedWithPage") {
     packageName.set("pagination.offsetBasedWithPage")
-    sourceFolder.set("pagination/offsetBasedWithPage")
+    srcDir("src/commonMain/graphql/pagination/offsetBasedWithPage")
     generateDataBuilders.set(true)
   }
   service("pagination.cursorBased") {
     packageName.set("pagination.cursorBased")
-    sourceFolder.set("pagination/cursorBased")
+    srcDir("src/commonMain/graphql/pagination/cursorBased")
     generateDataBuilders.set(true)
   }
   service("pagination.connection") {
     packageName.set("pagination.connection")
-    sourceFolder.set("pagination/connection")
+    srcDir("src/commonMain/graphql/pagination/connection")
     generateDataBuilders.set(true)
   }
 }

tests/runtime/build.gradle.kts

@@ -18,6 +18,6 @@ apollo {
   service("service") {
     generateDataBuilders.set(true)
     packageName.set("com.example")
-    schemaFile.set(file("../sample-server/src/main/resources/schema.graphqls"))
+    schemaFiles.from(file("../sample-server/src/main/resources/schema.graphqls"))
   }
 }

tests/websockets/build.gradle.kts

@@ -35,7 +35,7 @@ apollo {
   }?.forEach {
     service(it.name) {
       if (it.name == "sample-server") {
-        schemaFile.set(file("../sample-server/src/main/resources/schema.graphqls"))
+        schemaFiles.from(file("../sample-server/src/main/resources/schema.graphqls"))
       }
       srcDir(it)
       packageName.set(it.name.replace("-", "."))