Document update nuances

Author: sergiitk

build.gradle

@@ -579,7 +579,7 @@ tasks.register('checkForUpdates') {
             if (oldResolved != newResolved) {
                 def oldId = oldResolved.id.componentIdentifier
                 def newId = newResolved.id.componentIdentifier
-                println("${newId.group}:${newId.module} ${oldId.version} -> ${newId.version}")
+                println("libs.${name} = ${newId.group}:${newId.module} ${oldId.version} -> ${newId.version}")
             }
         }
     }

gradle/libs.versions.toml

@@ -2,9 +2,17 @@
 # Compatibility problem with internal version getting onto 1.5.3.
 # https://github.com/grpc/grpc-java/pull/9118
 googleauth = "1.4.0"
+# Update notes / 2023-07-19 sergiitk:
+#    Couldn't update to 32.1.1 because Guava 32.1.0 broke gradle metadata:
+#    https://github.com/google/guava/releases/tag/v32.1.0
+#    32.1.1 partially fixed this, but our build still breaks with:
+#    Could not resolve com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava.
+#
 # TODO(any release manager): attempt removing runtimeOnly dependencies when guava upgraded:
 # - okhttp: errorprone.annotations
-guava = "32.0.1-android"
+#
+# Allowed to be different from guava-jre.
+guava = '32.0.1-android'
 netty = '4.1.94.Final'
 # Keep the following references of tcnative version in sync whenever it's updated:
 #   SECURITY.md
@@ -26,29 +34,33 @@ animalsniffer-annotations = "org.codehaus.mojo:animal-sniffer-annotations:1.23"
 auto-value = "com.google.auto.value:auto-value:1.10.2"
 auto-value-annotations = "com.google.auto.value:auto-value-annotations:1.10.2"
 checkstyle = "com.puppycrawl.tools:checkstyle:10.12.1"
-checkstylejava8 = "com.puppycrawl.tools:checkstyle:9.3"
 commons-math3 = "org.apache.commons:commons-math3:3.6.1"
 conscrypt = "org.conscrypt:conscrypt-openjdk-uber:2.5.2"
 cronet-api = "org.chromium.net:cronet-api:108.5359.79"
 cronet-embedded = "org.chromium.net:cronet-embedded:108.5359.79"
 errorprone-annotations = "com.google.errorprone:error_prone_annotations:2.20.0"
-errorprone-corejava8 = "com.google.errorprone:error_prone_core:2.10.0"
 errorprone-core = "com.google.errorprone:error_prone_core:2.20.0"
 google-api-protos = "com.google.api.grpc:proto-google-common-protos:2.22.0"
 google-auth-credentials = { module = "com.google.auth:google-auth-library-credentials", version.ref = "googleauth" }
 google-auth-oauth2Http = { module = "com.google.auth:google-auth-library-oauth2-http", version.ref = "googleauth" }
+# Release notes: https://cloud.google.com/logging/docs/release-notes
 google-cloud-logging = "com.google.cloud:google-cloud-logging:3.15.5"
 gson = "com.google.code.gson:gson:2.10.1"
 guava = { module = "com.google.guava:guava", version.ref = "guava" }
 guava-betaChecker = "com.google.guava:guava-beta-checker:1.0"
 guava-testlib = { module = "com.google.guava:guava-testlib", version.ref = "guava" }
+# JRE version is needed for projects where its a transitive dependency, f.e. gcp-observability.
+# May be different from the -android version.
 guava-jre = "com.google.guava:guava:32.0.1-jre"
 hdrhistogram = "org.hdrhistogram:HdrHistogram:2.1.12"
 javax-annotation = "org.apache.tomcat:annotations-api:6.0.53"
 j2objc-annotations = " com.google.j2objc:j2objc-annotations:2.8"
 jetty-alpn-agent = "org.mortbay.jetty.alpn:jetty-alpn-agent:2.0.10"
 jsr305 = "com.google.code.findbugs:jsr305:3.0.2"
 junit = "junit:junit:4.13.2"
+# Update notes / 2023-07-19 sergiitk:
+#    Couldn't update to 5.4.0, updated to the last in 4.x line. Version 5.x breaks some tests.
+#    Error log: https://github.com/grpc/grpc-java/pull/10359#issuecomment-1632834435
 mockito-android = "org.mockito:mockito-android:4.11.0"
 mockito-core = "org.mockito:mockito-core:4.11.0"
 netty-codec-http2 = { module = "io.netty:netty-codec-http2", version.ref = "netty" }
@@ -75,3 +87,9 @@ robolectric = "org.robolectric:robolectric:4.10.3"
 signature-android = "net.sf.androidscents.signature:android-api-level-19:4.4.2_r4"
 signature-java = "org.codehaus.mojo.signature:java18:1.0"
 truth = "com.google.truth:truth:1.1.5"
+
+# Do not update: Pinned to the last version supporting Java 8.
+# See https://checkstyle.sourceforge.io/releasenotes.html#Release_10.1
+checkstylejava8 = "com.puppycrawl.tools:checkstyle:9.3"
+# See https://github.com/google/error-prone/releases/tag/v2.11.0
+errorprone-corejava8 = "com.google.errorprone:error_prone_core:2.10.0"