From 1f5ea9da55ee27d6ad6bfd1d3b2d2f604edae082 Mon Sep 17 00:00:00 2001
From: Valery Yatsynovich <valery_yatsynovich@epam.com>
Date: Thu, 5 Jan 2023 18:17:47 +0300
Subject: [PATCH] docs: Describe transitive Selenium dependencies management

---
 README.md                                  |  7 +++
 docs/transitive-dependencies-management.md | 68 ++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 docs/transitive-dependencies-management.md

diff --git a/README.md b/README.md
index 596d6e564..507aa8899 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,13 @@ dependencies {
 }
 ```
 
+### 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).
+Follow the [Transitive Dependencies Management article](docs/transitive-dependencies-management.md) for more information
+about establishing a fixed Selenium version for your Java test framework.
+
 ## Drivers Support
 
 Appium java client has dedicated classes to support the following Appium drivers:
diff --git a/docs/transitive-dependencies-management.md b/docs/transitive-dependencies-management.md
new file mode 100644
index 000000000..dc148d816
--- /dev/null
+++ b/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')
+}
+```