docs: promote use of bill of materials in quickstart documentation (#…

…1620)

Fixes #1552

README.md

@@ -50,35 +50,92 @@ credentials as well as utility methods to create them and to get Application Def
 
 ## Quickstart
 
+### Preferred method: using `java-libraries-bom`
+If your use case is to enable authentication for a GAPIC library such as `google-cloud-datastore`,
+you may want simply add `libraries-bom`, which automatically imports the auth bom, to your pom.xml
+as follows:
+
+[//]: # ({x-version-update-start:google-auth-library-bom:released})
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.cloud</groupId>
+      <artifactId>libraries-bom</artifactId>
+      <version>26.53.0</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
+Otherwise, if you don't plan using libraries-bom, see the next section on 
+_Google Auth Library Bill of Materials_.
+
+### Using Maven
+
+#### Google Auth Library Bill of Materials
+In order to ensure transitive dependencies and the modules themselves are aligned with each other,
+we rely on the Google Auth Library Bill of Materials. Please add this to your dependency management
+section as follows:
+
+[//]: # ({x-version-update-start:google-auth-library-bom:released})
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.auth</groupId>
+      <artifactId>google-auth-library-bom</artifactId>
+      <version>1.30.1</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+[//]: # ({x-version-update-end})
+
+#### Choosing your implementation
+
 If you are using Maven, add this to your pom.xml file (notice that you can replace
 `google-auth-library-oauth2-http` with any of `google-auth-library-credentials` and
 `google-auth-library-appengine`, depending on your application needs):
 
-[//]: # ({x-version-update-start:google-auth-library-oauth2-http:released})
-
 ```xml
 <dependency>
   <groupId>com.google.auth</groupId>
+  <!-- Let the BOM manage the module and dependency versions -->
+  <!-- Replace with the module(s) that are needed -->
   <artifactId>google-auth-library-oauth2-http</artifactId>
-  <version>1.19.0</version>
 </dependency>
 ```
-[//]: # ({x-version-update-end})
-
 
+### Using Gradle
 If you are using Gradle, add this to your dependencies
 
-[//]: # ({x-version-update-start:google-auth-library-oauth2-http:released})
+[//]: # ({x-version-update-start:google-auth-library-bom:released})
 ```Groovy
-implementation 'com.google.auth:google-auth-library-oauth2-http:1.19.0'
+dependencies {
+    // The BOM will manage the module versions and transitive dependencies
+    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
+    // Replace with the module(s) that are needed
+    implementation 'com.google.auth:google-auth-library-oauth2-http'
+}
+
 ```
 [//]: # ({x-version-update-end})
 
+Unfortunately, SBT [cannot](https://github.com/sbt/sbt/issues/4531) manage dependencies via Maven
+Bills of Materials. Therefore, you will have to add the submodule directly. Make sure the module
+versions are aligned in case you are using more than one authentication module in order to prevent
+transitive dependency conflicts.
 If you are using SBT, add this to your dependencies
 
 [//]: # ({x-version-update-start:google-auth-library-oauth2-http:released})
 ```Scala
-libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.19.0"
+// Replace this with the implementation module that suits your needs
+libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"
 ```
 [//]: # ({x-version-update-end})