Thank you, Gabriele, for the effort you put into moving our codebase forward and improving its maintainability.
On 2026/05/12 15:44:25 Gabriele Cardosi wrote: > We realized that the previous version (1) of the proposal did not > accurately reflect the real motivation behind the proposed changes. As a > result, it created unjustified expectations about both its goals and > non-goals. For this reason, we have decided to reframe the proposal by > renaming its title and providing a new description that better clarifies > its objectives. > > Context > The KIE codebase is composed, broadly, of two kinds of components: > > > 1. Common code (utility libraries, engine modules) > 2. Framework-specific code (Quarkus/Spring Boot) that exposes the above > and, eventually, adds framework-specific behavior > > > If an external dependency is used at both the common and framework-specific > levels, a lock-in occurs—i.e., the versions of the library used at both > levels must be compatible at both compile-time and runtime. > Since we are exposing common code through two different frameworks (Quarkus > and Spring Boot), this also implies that there must be compile-time and > runtime compatibility of dependency versions across the two frameworks. > This situation applies only to dependencies used at both the common and > framework levels. We refer to it as *dual-framework lock-in*, an > architectural issue inherent in the design of our codebase. > *The current proposal does not aim to address this issue, as its solution > is outside the scope of this discussion.* > > There are, however, other dependencies that are used only at one level > (either common or framework-specific). For these dependencies, such lock-in > does not exist, even if the library is used in both frameworks, provided it > is not used at the common level. The current proposal aims to simplify the > management of these dependencies. > While the above describes the architectural design—which is independent of > language and build tools—there is also the implementation aspect. > > Currently, dependency versions are scattered across multiple POMs in > different projects (Drools, Kogito Runtimes, OptaPlanner, Kogito Apps, > Kogito Examples). Sometimes a dependency version is overridden or declared > in specific submodules; sometimes versions used at framework levels clash, > and often it is unclear why a given version is inherited in the final > application. > > Other issues include: > > - Version declarations for KIE artifacts that no longer exist (e.g., in > Drools) > - Version declarations for KIE artifacts defined in downstream projects > (e.g., in Kogito Runtimes, there are declarations for Kogito Apps > artifacts), creating a violation of clean architecture principles > > > All of this makes dependency maintenance difficult, error-prone, and > time-consuming. > A notable example is CVE fixes, which currently must be applied in at least > three (or sometimes more) places. Even more problematic are framework > upgrades, which are affected not only by the dual-framework lock-in but > also by overrides that must be applied in multiple places—sometimes > unexpectedly, as observed during the last Quarkus upgrade. > > Scope > The scope of this proposal is to simplify our dependency management > structure and reduce the issues listed above. > The proposed solution aims to define only three sets of BOMs: > > - One for common code and external dependencies > - One for Quarkus > - One for Spring Boot > > > It also introduces a clear and unambiguous POM hierarchy that ultimately > converges to a single parent. > With this structure, navigation from any low-level POM to the top-level one > becomes straightforward, making it easy to identify where changes must be > applied. Additionally, it becomes simpler to determine beforehand which POM > needs modification under different scenarios. > > Approach > Three main principles guide this proposal: > Architectural Level > > - Enforce separation between the two framework-specific POM hierarchies > - Ensure all external dependency declarations converge into a single POM > > > Design Level > > > - Centralize version declarations into three well-defined BOMs > - Define the top-level POM (kie-parent, in the Drools project) to > contain all external dependency declarations > - For Quarkus: use kogito-quarkus-bom (in Kogito Runtimes) as the > top-level BOM > - Note: this already exists but is currently incomplete > - For Spring Boot: use kogito-spring-boot-bom (in Kogito Runtimes) as > the top-level BOM > - Note: this already exists but is currently incomplete > - In downstream projects, create framework-specific BOMs that extend > upstream ones, adding only project-specific modules > - Ensure a clear parent-child hierarchy that ultimately converges to > kie-parent > - Remove or block dependencyManagement tags in all POMs except the > designated BOMs > - Apply consistent enforcer rules across the entire codebase > > > Implementation Level > Introduce two enforcer rules: > > - no-dependency-management-tag: prohibits POMs from declaring > dependencyManagement sections, preventing duplication and accidental > version declarations > - no-external-managed-dependency-rule: prevents POMs from declaring > versions for modules outside the current project, avoiding references to > obsolete or external artifacts > > > With these rules in place, the following benefits are achieved: > > CVE fixes require changes in a single POM, easily located by traversing the > hierarchy to kie-parent > Framework-specific overrides also require modifications in a single, > clearly defined POM > Arbitrary version declarations are prevented, improving long-term > maintainability > Documentation (README files and comments) clarifies where and how version > updates should be applied > > > Recap > In conclusion, this proposal provides the following benefits: > > - Centralized version management (single source of truth) instead of > scattered definitions > - Reduced duplication and elimination of unnecessary overrides > - Clear separation between Quarkus and Spring Boot hierarchies > - A consistent, linear POM hierarchy converging on kie-parent > - Simplified overrides for framework-specific dependencies > - Strong architectural governance over version management > - Prevention of invalid or outdated dependency declarations > > Kudos to Yeser Amer and Chinchu P Shaji for their collaboration and support. > > --- > 1: https://lists.apache.org/thread/h0gpsvtxxdqq6mt9t1dnjn3s43kd0h3s > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
