build: correct duplicate-merge comment and clarify global scope of shipped keep-rules

Author: OmarAlJarrah

sdk-core/src/main/resources/META-INF/proguard/sdk-core.pro

@@ -66,5 +66,9 @@
 # Kotlin emits @Metadata on every class; reflective Kotlin tooling (including Jackson's Kotlin
 # module) reads it to recover constructor parameter names and nullability. Strip it and
 # data-class binding silently degrades, so keep the annotation across the toolkit.
+#
+# Scope note: `-keepattributes` is a global directive. Because this file ships under
+# META-INF/proguard, depending on sdk-core adds these attributes to the consumer's *entire*
+# program, not just the SDK's classes.
 -keepattributes RuntimeVisibleAnnotations,AnnotationDefault
 -keep class kotlin.Metadata { *; }

sdk-serde-jackson/src/main/resources/META-INF/proguard/sdk-serde-jackson.pro

@@ -20,6 +20,13 @@
 # conventional — and the only safe — consumer recommendation is to keep the databind, core, and
 # annotation packages wholesale, retain the attributes Jackson reflects over, and keep every
 # annotation enum intact.
+#
+# Scope note: because this file ships under META-INF/proguard, R8/AGP applies it to the consumer's
+# entire program, not just the SDK's classes. The wholesale Jackson `-keep` rules below therefore
+# exempt the consumer's *entire* Jackson surface from shrinking — including any Jackson the app uses
+# directly, elsewhere. The `-keepattributes` directive is likewise global: it adds these attributes
+# to the whole consumer build, not only to SDK classes. An app that wants tighter shrinking can
+# override these rules in its own configuration.
 -keepattributes Signature,*Annotation*,EnclosingMethod,InnerClasses
 -keep class com.fasterxml.jackson.databind.** { *; }
 -keep class com.fasterxml.jackson.core.** { *; }

sdk-shrink-test/build.gradle.kts

@@ -87,8 +87,11 @@ val shippedConsumerRulePaths: List<String> =
     )
 
 // Bundle the consumer program and its entire runtime classpath into one jar — the program R8 will
-// shrink. Service-loader manifests are concatenated; other duplicates (e.g. repeated module
-// metadata, signature files) are dropped so the merged jar stays valid.
+// shrink. `DuplicatesStrategy.EXCLUDE` keeps only the first occurrence of any duplicated path and
+// skips the rest; it does not merge. That includes service-loader manifests — colliding
+// `META-INF/services/<iface>` entries are NOT concatenated, only the first wins. It happens not to
+// matter for the current classpath (no colliding service files), but a future dependency that
+// ships one would need explicit concatenation (e.g. a Shadow `ServiceFileTransformer`) here.
 val buildShrinkInputJar by tasks.registering(Jar::class) {
     group = "shrink"
     description = "Bundles the consumer program and its runtime classpath into the R8 input jar."

sdk-shrink-test/src/main/kotlin/org/dexpace/sdk/shrinktest/ShrinkSurvivalApp.kt

@@ -26,10 +26,9 @@ import org.dexpace.sdk.transport.okhttp.OkHttpTransport
  * seams — the same surface the shipped `META-INF/proguard` consumer rules protect — and prints
  * [SUCCESS_SENTINEL] on a clean run.
  *
- * The harness runs this twice: once from the un-shrunk jar to establish the baseline, and once
- * from the R8-shrunk jar. Because the shrunk run performs a real HTTP round-trip and a real JSON
- * round-trip, it proves not merely that the kept classes still exist but that their members
- * remain wired correctly after tree-shaking and (potential) renaming.
+ * The harness runs this from the R8-shrunk jar. Because that run performs a real HTTP round-trip
+ * and a real JSON round-trip, it proves not merely that the kept classes still exist but that their
+ * members remain wired correctly after tree-shaking and (potential) renaming.
  */
 public object ShrinkSurvivalApp {
     /** Printed verbatim to stdout once every exercise below has passed. */