fix: fix: improve message on version misalignment, change level to debug unless minor-level mismatch (#567)

Author: metacosm

core/deployment/pom.xml

@@ -46,6 +46,11 @@
       <groupId>io.fabric8</groupId>
       <artifactId>crd-generator-api</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.semver4j</groupId>
+      <artifactId>semver4j</artifactId>
+      <version>4.3.0</version>
+    </dependency>
     <dependency>
       <groupId>io.dekorate</groupId>
       <artifactId>kubernetes-annotations</artifactId>

core/deployment/src/main/java/io/quarkiverse/operatorsdk/deployment/OperatorSDKProcessor.java

@@ -14,6 +14,8 @@
 
 import org.jboss.jandex.DotName;
 import org.jboss.logging.Logger;
+import org.semver4j.Semver;
+import org.semver4j.Semver.VersionDiff;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 
@@ -134,12 +136,20 @@ void updateControllerConfigurations(
     }
 
     private void checkVersionCompatibility(String found, String expected, String name) {
-        if (!found.equals(expected)) {
-            String message = "Incompatible " + name + " version found: \"" + found + "\", expected: \"" + expected + "\"";
+        final var foundVersion = Semver.coerce(found);
+        final var expectedVersion = Semver.coerce(expected);
+        if (!expectedVersion.equals(foundVersion)) {
+            String message = "Mismatched " + name + " version found: \"" + found + "\", expected: \"" + expected + "\"";
             if (buildTimeConfiguration.failOnVersionCheck) {
                 throw new RuntimeException(message);
             } else {
-                log.warn(message);
+                final var diff = expectedVersion.diff(foundVersion);
+                if (diff.compareTo(VersionDiff.MINOR) >= 0) {
+                    log.warn(message
+                            + " by at least a minor version and things might not work as expected.");
+                } else {
+                    log.debug(message);
+                }
             }
         }
     }

core/runtime/src/main/java/io/quarkiverse/operatorsdk/runtime/BuildTimeOperatorConfiguration.java

@@ -59,7 +59,15 @@ public class BuildTimeOperatorConfiguration {
     public Boolean stopOnInformerErrorDuringStartup;
 
     /**
-     * Whether to fail or only emit a warning on version validation at compile time.
+     * Whether to fail or emit a debug-level (warning-level when misalignment is at the minor or above version level) log when
+     * the extension detects that there are misaligned versions.
+     * <p/>
+     * The following versions are checked for alignment:
+     * <ul>
+     * <li>declared Quarkus version used to build the extension vs. actually used Quarkus version at runtime</li>
+     * <li>Fabric8 client version used by JOSDK vs. actually used Fabric8 client version</li>
+     * <li>Fabric8 client version used by Quarkus vs. actually used Fabric8 client version</li>
+     * </ul>
      */
     @ConfigItem(defaultValue = "false")
     public Boolean failOnVersionCheck;

docs/modules/ROOT/pages/includes/quarkus-operator-sdk.adoc

@@ -206,7 +206,11 @@ a|icon:lock[title=Fixed at build time] [[quarkus-operator-sdk_quarkus.operator-s
 
 [.description]
 --
-Whether to fail or only emit a warning on version validation at compile time.
+Whether to fail or emit a debug-level (warning-level when misalignment is at the minor or above version level) log when the extension detects that there are misaligned versions. 
+The following versions are checked for alignment:  
+ - declared Quarkus version used to build the extension vs. actually used Quarkus version at runtime 
+ - Fabric8 client version used by JOSDK vs. actually used Fabric8 client version 
+ - Fabric8 client version used by Quarkus vs. actually used Fabric8 client version
 
 ifdef::add-copy-button-to-env-var[]
 Environment variable: env_var_with_copy_button:+++QUARKUS_OPERATOR_SDK_FAIL_ON_VERSION_CHECK+++[]

samples/exposedapp/pom.xml

@@ -22,6 +22,8 @@
         <groupId>io.quarkiverse.operatorsdk</groupId>
         <artifactId>quarkus-operator-sdk-bom</artifactId>
         <version>${project.version}</version>
+        <scope>import</scope>
+        <type>pom</type>
       </dependency>
     </dependencies>
   </dependencyManagement>