Page History

...

I propose adding two focused validation tasks to Kafka's Gradle build known collectively as the Automated Integrity Validation (AIV) Gate that Gate that catch the two most damaging categories of low-quality contributions: scaffolding-heavy PRs with no real logic, and code that violates Kafka's specific architectural rules. This effectively addresses the "Reviewer Overload" crisis while maintaining Kafka's domain-specific invariants and ensuring 100% local data sovereignty.

...

I propose adding an AIV Gate using Gradle's includeBuild composite build feature. This relies on native Java classes that live inside the Kafka repository  no repository   no external dependencies beyond JavaParser (build-time only, same pattern as Checkstyle/SpotBugs). Developers run them locally with ./gradlew checkContributionQuality, and CI runs them automatically as part of ./gradlew check.

...

1. Legitimate Core Fix (LDR = 0.91): A PR modifying replication logic inside ReplicaManager.java. It adds no new classes and one new private method (weight 1). It contains one if block (weight 5) and three variable assignments (weight 6). Total logic = 11, total structure = 1. LDR = 11 / 12 = 0.91. It passes easily.

2. Interface/Config Addition (Bypassed): A PR adding a new ConfigDef or Java interface. Files where ≥80% of top-level type declarations are interface or @interface types are dynamically evaluated under a "declarative profile" exception, allowing them to pass regardless of the LDR score. The 80% threshold will be validated during Shadow Mode and adjusted if necessary.

3. AI Slop/Boilerplate (LDR = 0.18): A PR generating an expansive new module wrapper. It contains 3 new classes (weight 3), 15 empty methods or simple getters (weight 15), massive Javadoc blocks (ignored), and only 2 actual method calls (weight 4). Total logic = 4, total structure = 18. LDR = 4 / 22 = 0.18. It falls below the 0.25 threshold, and the PR is blocked.

...

• Secure Emergency Bypass: Adding /aiv skip in any commit message skips all gates, but only if the GitHub Actions actor is verified against the official Apache Gitbox LDAP COMMITTERS list. Bots and external contributors cannot bypass the gate.

• Auditability: All bypasses are explicitly logged in the GitHub Actions CI step summary for transparency.

Compatibility, Deprecation, and Migration Plan

This proposal does not change the Kafka protocol or public APIs. It adds only internal build logic.

Migration: None. Existing code passes both checks (validated against trunk). The tasks only evaluate changed files in a PR diff, not the entire codebase.

...

Diagnostic Reports (A Mentorship Framework)

Instead of a cryptic failure once Shadow Mode ends, the tool posts a diagnostic summary in the CI output: "This PR's Logic Density is 0.18 (Threshold: 0.25). It appears to be mostly scaffolding. Try moving logic to the internal Config classes to improve density." This provides a clear, mentorship-oriented path to "ready" without bottlenecking legitimate contributions.

Compatibility, Deprecation, and Migration Plan

This proposal does not change the Kafka protocol or public APIs. It adds only internal build logic.

Migration: None. Existing code passes both checks (validated against trunk). The tasks only evaluate changed files in a PR diff, not the entire codebase.

Test Plan

To guarantee zero disruption to developer velocity, this KIP relies on strict unit testing and a phased CI rollout.

1. Unit Tests (JUnit 5 in build-plugins/src/test/):

• DensityAnalyzerTest:

  • Case: 150 lines of Javadoc with a single return statement -> LDR = 0.05 -> FAILS.

  • Case: 20 lines of branching if/while logic -> LDR = 0.45 -> PASSES.

  • Case: PR adds a pure interface with 10 method signatures -> Declarative Profile -> PASSES.

  • Case: PR removes 100 lines of dead code -> Net LOC negative -> SKIPS check.

• DesignComplianceCheckerTest:

  • Case: File initializes KafkaConsumer and passes it to Executors.newFixedThreadPool(5) -> FAILS (consumer-thread-safety violation).

  • Case: File initializes KafkaConsumer in a standard single-threaded poll loop -> PASSES.

  • Case: File contains only interface declarations with no trigger patterns -> PASSES (no rules applicable).

2. Shadow Mode (30-Day Data Collection):

Upon merge, the GitHub Action will run with continue-on-error: true. It will log results (Pass/Fail, LDR score, AST violations)

...

to the GitHub Actions step summary for 30 days without blocking PRs. During this time, the PMC will publish a sensitivity analysis of the historical data.

Exit Criteria: The gate will be promoted to blocking status via lazy consensus on the dev list once the false-positive rate is below 2% over a minimum of 50 evaluated PRs

Exit Criteria: The gate will be promoted to blocking status via lazy consensus on the dev list once the false-positive rate is below 2% over a minimum of 50 evaluated PRs.

Diagnostic Reports (A Mentorship Framework)

Instead of a cryptic failure once Shadow Mode ends, the tool posts a diagnostic summary in the CI output: "This PR's Logic Density is 0.18 (Threshold: 0.25). It appears to be mostly scaffolding. Try moving logic to the internal Config classes to improve density." This provides a clear, mentorship-oriented path to "ready" without bottlenecking legitimate contributions.

Future Work

To keep this KIP tightly scoped to achievable build validation tasks, the following enhancements are deferred to future proposals:

...

• Q: How does the gate handle refactoring?

  A: AIV includes a "Refactor Exception" f  if a PR removes more lines than it adds (net-negative lines), the density check is automatically bypassed.

• Q: What happens with trivial PRs, like fixing a single typo in a Javadoc? Won't the LDR score be 0?

  A: The Gradle task includes a minimum line-change threshold. Trivial PRs (e.g., modifying fewer than 10 lines of code) bypass the LDR check entirely to ensure minor documentation fixes or typo corrections are never blocked.

• Q: Does LDR penalize good documentation?

  A: No. The AST analyzer ignores Javadoc and comments entirely, focusing only on executable nodes.

• Q: What about Kotlin and Scala code?

  A: This initial KIP applies exclusively to Java files. Kotlin, Scala, Shell scripts, and configuration files are completely bypassed until dedicated parsers are proposed in a future KIP.

• Q: What if a PR modifies both Java and non-Java files?

  A: The AIV Gate evaluates only the Java files in the diff. Non-Java files are ignored entirely in this initial KIP.

Design Gate (Architecture)

...