From 00c172e902f833ca1806284c5799d79bf6377f7d Mon Sep 17 00:00:00 2001
From: Rene Groeschke <rene@elastic.co>
Date: Wed, 13 Oct 2021 11:23:37 +0200
Subject: [PATCH] Document how to test a dev version of a 3party dependency
 (#78962)

* Document how to test a dev version of a 3party dependency

- Introduce a FAQ section to BUILDING.MD
- Provide three solutions to test and use a custom third party dependency
in our elasticsearch build

* Fix jitpack repo declaration

* Tweak formatting

* Apply review feedback

Co-authored-by: Rory Hunter <pugnascotia@users.noreply.github.com>

* Apply further review feedback

Co-authored-by: Rory Hunter <pugnascotia@users.noreply.github.com>

* Tweak recommendations for replacing a dependency

Apply review feedback

* Elaborate on dependency declaration to resolves jars from flat dir repositories

Co-authored-by: Rory Hunter <pugnascotia@users.noreply.github.com>
---
 BUILDING.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/BUILDING.md b/BUILDING.md
index c41c31f72cb5..01f24613968b 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -135,3 +135,99 @@ dependencies {
   }
 }
 ```
+
+## FAQ
+
+### How do I test a development version of a third party dependency?
+
+To test an unreleased development version of a third party dependency you have several options.
+
+#### How to use a maven based third party dependency via mavenlocal?
+
+1. Clone the third party repository locally
+2. Run `mvn install` to install copy into your `~/.m2/repository` folder.
+3. Add this to the root build script:
+
+```
+   allprojects {
+     repositories {
+         mavenLocal()
+     }
+   }
+   ```
+4. Update the version in your dependency declaration accordingly (likely a snapshot version)
+5. Run the gradle build as needed
+
+#### How to use a maven built based third party dependency with jitpack repository?
+
+https://jitpack.io is an adhoc repository that supports building maven projects transparently in the background when 
+resolving unreleased snapshots from a github repository. This approach also works as temporally solution
+and is compliant with our CI builds. 
+
+1. Add the JitPack repository to the root build file:
+
+```
+   allprojects {
+     repositories {
+        maven { url "https://jitpack.io" }
+     }
+   }
+```
+2. Add the dependency in the following format
+```
+dependencies {
+  implementation 'com.github.User:Repo:Tag'
+}
+```
+
+As version you could also use a certain short commit hash or `master-SNAPSHOT`.
+In addition to snapshot builds JitPack supports building Pull Requests. Simply use PR<NR>-SNAPSHOT as the version.
+
+3. Run the gradle build as needed. Keep in mind the initial resolution might take a bit longer as this needs to be built 
+by JitPack in the background before we can resolve the adhoc built dependency. 
+
+---
+
+**NOTE**
+
+You should only use that approach locally or on a developer branch for for production dependencies as we do
+not want to ship unreleased libraries into our releases.
+---
+
+#### How to use a custom third party artifact?
+
+For third party libraries that are not built with maven (e.g. ant) or provided as a plain jar artifact we can leverage
+a flat directory repository that resolves artifacts from a flat directory on your filesystem.
+
+1. Put the jar artifact with the format `artifactName-version.jar` into a directory named `localRepo` (you have to create this manually)
+2. Declare a flatDir repository in your root build.gradle file
+
+```
+allprojects { 
+  repositories {
+      flatDir {
+          dirs 'localRepo'
+      }
+  }
+}
+```
+
+3. Update the dependency declaration of the artifact in question to match the custom build version. For a file named e.g. `jmxri-1.2.1.jar` the 
+  dependency definition would be `:jmxri:1.2.1` as it comes with no group information:
+  
+  ```
+  dependencies {
+      implementation ':jmxri:1.2.1'
+  }
+  ```
+4. Run the gradle build as needed.
+
+---
+**NOTE**
+
+As Gradle prefers to use modules whose descriptor has been created from real meta-data rather than being generated,
+flat directory repositories cannot be used to override artifacts with real meta-data from other repositories declared in the build.
+For example, if Gradle finds only `jmxri-1.2.1.jar` in a flat directory repository, but `jmxri-1.2.1.pom` in another repository
+that supports meta-data, it will use the second repository to provide the module.
+Therefore it is recommended to declare a version that is not resolveable from public repositories we use (e.g. maven central)
+---