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
