doc: explain how to deal with dependency convergence errors (#837)

* doc: explain how to deal with dependency convergence errors

* doc: `mvn` command

* fix: )

* style: better comments

* doc: add comments to the consumers too

Author: c-dilks

common-tools/clas-tracking/pom.xml

@@ -24,7 +24,7 @@
     </dependency>
     <dependency>
       <groupId>org.ejml</groupId>
-      <artifactId>ejml-simple</artifactId>
+      <artifactId>ejml-simple</artifactId> <!-- WARNING: don't override the version number from the top-level dependencyManagement; see `docs/dependency_conflicts.md` -->
     </dependency>
     <dependency>
       <groupId>gov.nist.math</groupId>

common-tools/coat-libs/pom.xml

@@ -38,13 +38,11 @@
     <dependency>
       <groupId>j4ml</groupId>
       <artifactId>j4ml-neuroph</artifactId>
-      <version>0.9-SNAPSHOT</version>
     </dependency>
 
     <dependency>
       <groupId>j4ml</groupId>
       <artifactId>j4ml-clas12</artifactId>
-      <version>0.9-SNAPSHOT</version>
     </dependency>
 
     <dependency>

docs/dependency_conflicts.md

@@ -0,0 +1,28 @@
+# Handling Dependency Conflicts
+
+We have a `dependencyManagement` section in [the top-level `pom.xml`](/pom.xml); some of the dependencies within are used to set versions of certain transitive dependencies. For example, let's say we have dependencies `dep:A`, `dep:B`, and `dep:C`.
+
+- `dep:A` depends on version 1.1 of `dep:C`
+- `dep:B` depends on version 1.5 of `dep:C`
+
+Coatjava depends on `dep:A` and `dep:B`, and so the `maven-enforcer-plugin` will complain about a "dependency convergence error" of `dep:C`, since the version numbers are different (1.1 vs. 1.5).
+
+To resolve this conflict, a typical strategy is to choose the _later_ version of the two, in this case, `dep:C` version 1.5. We can do this by explicitly defining dependency `dep:C` in a `dependencyManagement` section as such:
+
+```xml
+<dependency>
+  <groupId>dep</groupId>
+  <artifactId>C</artifactId>
+  <version>1.5</version>
+</dependency>
+```
+
+Coatjava will then use 1.5 as needed.
+
+Dependabot, however, will routinely try to update the `dep:C` version, to the _latest_ available version of `dep:C`. When this happens, please do the following:
+
+1. Comment out the `dependency` specification
+2. Rebuild coatjava, which will cause `maven-enforcer-plugin` to complain; that will tell you the versions
+   - alternatively, run `mvn enforcer:enforce -Drules=dependencyConvergence`, but that may not exclude dependencies that we _don't_ want to enforce convergence on (_e.g._, `com.google.protobuf:protobuf-java`)
+3. Update the version number, if needed, by choosing the _later_ of the two conflicting versions
+4. Unless `dep:A` or `dep:B` are keeping _their_ version of `dep:C` dependency up-to-date, you will likely find that Dependabot is suggesting a version that is _too_ new; in that case, just close Dependabot's PR and await updates of `dep:A` or `dep:B`

pom.xml

@@ -113,7 +113,7 @@
       <dependency>
         <groupId>org.jlab.coda</groupId>
         <artifactId>jclara</artifactId>
-        <version>4.3-SNAPSHOT</version>
+        <version>4.3-SNAPSHOT</version> <!-- WARNING: if changed, check the `com.google.code.gson:gson` version; see `docs/dependency_conflicts.md` -->
       </dependency>
 
       <dependency>
@@ -144,13 +144,31 @@
       <dependency>
         <groupId>org.jlab.jnp</groupId>
         <artifactId>jnp-hipo</artifactId>
-        <version>2.0-SNAPSHOT</version>
+        <version>2.0-SNAPSHOT</version> <!-- WARNING: if changed, check the `net.objecthunter:exp4j` version; see `docs/dependency_conflicts.md` -->
       </dependency>
 
       <dependency>
         <groupId>org.jlab.jnp</groupId>
         <artifactId>jnp-hipo4</artifactId>
-        <version>4.3-SNAPSHOT</version>
+        <version>4.3-SNAPSHOT</version> <!-- WARNING: if changed, check the `net.objecthunter:exp4j` version; see `docs/dependency_conflicts.md` -->
+      </dependency>
+
+      <dependency>
+        <groupId>j4ml</groupId>
+        <artifactId>j4ml-neuroph</artifactId>
+        <version>0.9-SNAPSHOT</version>
+      </dependency>
+
+      <dependency>
+        <groupId>j4ml</groupId>
+        <artifactId>j4ml-data</artifactId>
+        <version>0.9-SNAPSHOT</version>
+      </dependency>
+
+      <dependency>
+        <groupId>j4ml</groupId>
+        <artifactId>j4ml-clas12</artifactId>
+        <version>0.9-SNAPSHOT</version> <!-- WARNING: if changed, check the `org.ejml:ejml-simple` version; see `docs/dependency_conflicts.md` -->
       </dependency>
 
       <dependency>
@@ -165,33 +183,43 @@
         <version>1.0.3</version>
       </dependency>
 
-      <dependency>
+      <dependency> <!-- sets version number for all 'ai.djl' dependencies -->
         <groupId>ai.djl</groupId>
         <artifactId>bom</artifactId>
-        <version>0.34.0</version> <!-- sets version number for all 'ai.djl' dependencies -->
+        <version>0.34.0</version> <!-- WARNING: if changed, check the `com.google.code.gson:gson` version; see `docs/dependency_conflicts.md` -->
         <type>pom</type>
         <scope>import</scope>
       </dependency>
 
       <!-- BEGIN DEPENDENCY CONFLICT RESOLUTION -->
-      <!-- the following dependency versions are specified to resolve dependency tree conflicts; see also exclusions in `maven-enforcer-plugin` -->
-
-      <dependency> <!-- conflict between `org.jlab.jnp:jnp-hipo:jar:2.0-SNAPSHOT` and `org.jlab.jnp:jnp-hipo4:jar:4.3-SNAPSHOT` -->
+      <!--
+        the following dependency versions are specified to resolve dependency tree conflicts
+        - see also exclusions in `maven-enforcer-plugin`
+        - see `docs/dependency_conflicts.md` for more info
+      -->
+
+      <!-- resolve conflict between `org.jlab.jnp:jnp-hipo:jar:2.0-SNAPSHOT` and `org.jlab.jnp:jnp-hipo4:jar:4.3-SNAPSHOT`
+           by choosing the later version of their `net.objecthunter:exp4j` dependency -->
+      <dependency>
         <groupId>net.objecthunter</groupId>
         <artifactId>exp4j</artifactId>
-        <version>0.4.8</version> <!-- choose the later version -->
+        <version>0.4.8</version> <!-- WARNING: if changed, see `docs/dependency_conflicts.md` -->
       </dependency>
 
-      <dependency> <!-- resolve conflict between `org.jlab.coda:jclara` and `ai.djl:api` -->
+      <!-- resolve conflict between `org.jlab.coda:jclara` and `ai.djl:api`
+           by choosing the later version of their `com.google.code.gson:gson` dependency -->
+      <dependency>
         <groupId>com.google.code.gson</groupId>
         <artifactId>gson</artifactId>
-        <version>2.13.1</version> <!-- choose the later version -->
+        <version>2.13.1</version> <!-- WARNING: if changed, see `docs/dependency_conflicts.md` -->
       </dependency>
 
-      <dependency> <!-- resolve conflict between `j4ml:j4ml-clas12` and `clas-tracking` -->
+      <!-- resolve conflict between `j4ml:j4ml-clas12` and `clas-tracking`
+           by using the version of `org.ejml:ejml-simple` used by `j4ml:j4ml-clas12:jar:0.9-SNAPSHOT` -->
+      <dependency>
         <groupId>org.ejml</groupId>
         <artifactId>ejml-simple</artifactId>
-        <version>0.40</version> <!-- match version from `j4ml:j4ml-clas12:jar:0.9-SNAPSHOT` -->
+        <version>0.40</version> <!-- WARNING: if changed, see `docs/dependency_conflicts.md` -->
       </dependency>
 
       <!-- END DEPENDENCY CONFLICT RESOLUTION -->

reconstruction/mltn/pom.xml

@@ -23,19 +23,16 @@
     <dependency>
       <groupId>j4ml</groupId>
       <artifactId>j4ml-neuroph</artifactId>
-      <version>0.9-SNAPSHOT</version>
     </dependency>
 
     <dependency>
       <groupId>j4ml</groupId>
       <artifactId>j4ml-data</artifactId>
-      <version>0.9-SNAPSHOT</version>
     </dependency>
 
     <dependency>
       <groupId>j4ml</groupId>
       <artifactId>j4ml-clas12</artifactId>
-      <version>0.9-SNAPSHOT</version>
     </dependency>
 
     <dependency>