docs: Describe transitive Selenium dependencies management

Author: valfirst

README.md

@@ -8,15 +8,15 @@ This is the Java language bindings for writing Appium Tests that conform to [Web
 
 ## v8 Migration
 
-Since version 8 Appium Java Client had several major changes, which might require to 
+Since version 8 Appium Java Client had several major changes, which might require to
 update your client code. Make sure to follow the [v7 to v8 Migration Guide](https://github.com/appium/java-client/blob/master/docs/v7-to-v8-migration-guide.md)
 in order to streamline the migration process.
 
 ## Add Appium java client to your test framework
 
 ### Stable
 
-#### Maven 
+#### Maven
 
 Add the following to pom.xml:
 
@@ -57,19 +57,19 @@ Add the following to pom.xml:
 ```
 
 Add the dependency:
- 
+
 ```xml
 <dependency>
     <groupId>com.github.appium</groupId>
     <artifactId>java-client</artifactId>
     <version>latest commit ID from master branch</version>
 </dependency>
-``` 
+```
 
 #### Gradle
 
 Add the JitPack repository to your build file. Add it in your root build.gradle at the end of repositories:
- 
+
 ```groovy
 allprojects {
     repositories {
@@ -80,13 +80,20 @@ allprojects {
 ```
 
 Add the dependency:
- 
+
 ```groovy
 dependencies {
     implementation 'com.github.appium:java-client:latest commit id from master branch'
 }
 ```
 
+### How to pin Selenium dependencies?
+
+Appium Java Client declares Selenium dependencies using open version range which is handled in differently by different
+build tools. Sometimes users may want to pin used Selenium dependencies for [various reasons](https://github.com/appium/java-client/issues/1823).
+You can find samples how it can be achieved using [Maven](docs/transitive-dependencies-management.md#maven) or
+[Gradle](docs/transitive-dependencies-management.md#gradle) in the docs.
+
 ## Drivers Support
 
 Appium java client has dedicated classes to support the following Appium drivers:
@@ -98,7 +105,7 @@ Appium java client has dedicated classes to support the following Appium drivers
 - [Gecko](https://github.com/appium/appium-geckodriver): [GeckoDriver](src/main/java/io/appium/java_client/gecko/GeckoDriver.java)
 - [Mac2](https://github.com/appium/appium-mac2-driver): [Mac2Driver](src/main/java/io/appium/java_client/mac/Mac2Driver.java)
 
-To automate other platforms that are not listed above you could use 
+To automate other platforms that are not listed above you could use
 [AppiumDriver](src/main/java/io/appium/java_client/AppiumDriver.java) or its custom derivatives.
 
 Appium java client is built on top of Selenium and implements same interfaces that the foundation
@@ -197,7 +204,7 @@ try {
 
 Check the corresponding driver's READMEs to know the list of capabilities and features it supports.
 
-You could find much more code examples by checking client's 
+You could find much more code examples by checking client's
 [unit and integration tests](src/test/java/io/appium/java_client).
 
 ## Troubleshooting
@@ -207,7 +214,7 @@ You could find much more code examples by checking client's
 Appium Java client uses reflective access to private members of other modules
 to ensure proper functionality of several features, like Page Object model.
 If you get a runtime exception and `InaccessibleObjectException` is present in
-the stacktrace, and your Java runtime is at version 16 or higher, then consider following 
+the stacktrace, and your Java runtime is at version 16 or higher, then consider following
 [Oracle's tutorial](https://docs.oracle.com/en/java/javase/16/migrate/migrating-jdk-8-later-jdk-releases.html#GUID-7BB28E4D-99B3-4078-BDC4-FC24180CE82B)
 and/or checking [existing issues](https://github.com/appium/java-client/search?q=InaccessibleObjectException&type=issues)
 for possible solutions. Basically, the idea there would be to explicitly allow
@@ -223,9 +230,9 @@ framework code rather than run separately by a script or manually. Depending
 on the way the server process is started it may or may not inherit the currently
 active shell environment. That is why you may still receive errors about variables
 presence even though these variables ar actually defined for your command line interpreter.
-Again, there is no universal solution to that, as there are many ways to spin up a new 
+Again, there is no universal solution to that, as there are many ways to spin up a new
 server process. Consider checking the [Appium Environment Troubleshooting](docs/environment.md)
-document for more information on how to debug and fix process environment issues. 
+document for more information on how to debug and fix process environment issues.
 
 ## Changelog
 

docs/transitive-dependencies-management.md

@@ -0,0 +1,68 @@
+# Maven
+
+Maven downloads dependency of [the latest version](https://cwiki.apache.org/confluence/display/MAVENOLD/Dependency+Mediation+and+Conflict+Resolution#DependencyMediationandConflictResolution-DependencyVersionRanges)
+matching the declared range by default, in other words whenever new versions of Selenium 4 libraries are published
+they are pulled transitively as Appium Java Client dependencies at the first project (re)build automatically.
+
+In order to pin Selenium dependencies they should be declared in `pom.xml` in the following way:
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>io.appium</groupId>
+        <artifactId>java-client</artifactId>
+        <version>X.Y.Z</version>
+        <exclusions>
+            <exclusion>
+                <groupId>org.seleniumhq.selenium</groupId>
+                <artifactId>selenium-api</artifactId>
+            </exclusion>
+            <exclusion>
+                <groupId>org.seleniumhq.selenium</groupId>
+                <artifactId>selenium-remote-driver</artifactId>
+            </exclusion>
+            <exclusion>
+                <groupId>org.seleniumhq.selenium</groupId>
+                <artifactId>selenium-support</artifactId>
+            </exclusion>
+        </exclusions>
+    </dependency>
+    <dependency>
+        <groupId>org.seleniumhq.selenium</groupId>
+        <artifactId>selenium-api</artifactId>
+        <version>A.B.C</version>
+    </dependency>
+    <dependency>
+        <groupId>org.seleniumhq.selenium</groupId>
+        <artifactId>selenium-remote-driver</artifactId>
+        <version>A.B.C</version>
+    </dependency>
+    <dependency>
+        <groupId>org.seleniumhq.selenium</groupId>
+        <artifactId>selenium-support</artifactId>
+        <version>A.B.C</version>
+    </dependency>
+</dependencies>
+```
+
+# Gradle
+
+Gradle uses [Module Metadata](https://docs.gradle.org/current/userguide/publishing_gradle_module_metadata.html)
+to perform improved dependency resolution whenever it is available. Gradle Module Metadata for Appium Java Client is
+published automatically with every release and is available on Maven Central.
+
+Appium Java Client declares [preferred](https://docs.gradle.org/current/userguide/rich_versions.html#rich-version-constraints)
+Selenium dependencies version which is equal to the lowest boundary in the version range, i.e. the lowest compatible
+Selenium dependencies are pulled by Gradle by default. It's strictly recommended to do not use versions lower than the
+range boundary, because unresolvable compilation and runtime errors may occur.
+
+In order to use newer Selenium dependencies they should be explicitly added to Gradle build script (`build.gradle`):
+
+```gradle
+dependencies {
+    implementation('io.appium:java-client:X.Y.Z')
+    implementation('org.seleniumhq.selenium:selenium-api:A.B.C')
+    implementation('org.seleniumhq.selenium:selenium-remote-driver:A.B.C')
+    implementation('org.seleniumhq.selenium:selenium-support:A.B.C')
+}
+```