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,16 @@
 # 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. TBD TBD
+#
+# Allowed to be different from guava-jre.
+#
 # TODO(any release manager): attempt removing runtimeOnly dependencies when guava upgraded:
 # - okhttp: errorprone.annotations
-guava = "32.0.1-android"
+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,13 +33,11 @@ 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" }
@@ -42,6 +47,8 @@ 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"
@@ -75,3 +82,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"