Page History

...

2. Shadow Mode (30-Day Rollout): 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. Once the PMC validates that the false-positive rate is practically zero, we will remove the continue-on-error flag to make it a mandatory, blocking check.

FAQ:

Q: Won't failing a CI check generate massive email spam to the dev@kafka mailing list?

 A A: No. To ensure zero spam, the check does not post comments or fail loudly in a way that emails the list. If a PR falls below the density threshold, a GitHub Action silently executes gh pr ready --undo to convert the PR into a Draft and applies a needs-substance label. This removes it from the review queue silently.

Q: Checkstyle already handles our code quality. Why do we need a new AST Design Gate?

 A A: Checkstyle is fantastic for formatting and simple regex (like blocking System.exit), but it struggles with complex, conditional architectural logic. For instance, Checkstyle cannot easily enforce "If KafkaConsumer is used, ensure it is not wrapped in java.util.concurrent." This custom task handles the architectural patterns that Checkstyle structurally cannot.

Q: What if the script has a bug and blocks legitimate human contributors?

 A A: The system prioritizes developer velocity. Any developer can bypass the gate immediately by adding /skip-validation to their commit message or PR description. Additionally, the initial 30-day "Shadow Mode" runs non-blocking, allowing the PMC to review its accuracy before it ever gains the power to block a merge.

Q: Will this block my emergency hotfix?

A: No. Any committer can bypass all gates by adding /aiv skip to the commit message.

Q.Does LDR penalize good documentation?

A: No. The Logic Density Ratio is designed to ignore comments and javadocs, focusing strictly on executable AST (Abstract Syntax Tree) nodes.

Q: How does the gate handle refactoring?

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

Q: Is my code being sent to an external AI?

A: No. The AIV Gate is designed for 100% local execution and does not require external API keys or cloud processing.

Q: Does this check Scala code?

A: Yes. For Scala and other non-Java files, the system uses Shannon entropy to detect repetitive, low-substance boilerplate.

Q: How do I know if my PR will fail before I push it?

A: You can run ./gradlew checkContributionQuality locally to get your LDR score and AST violation report before committing.

Q: Will this block my emergency hotfix?

A: No. Committers can bypass all gates by adding /aiv skip or /skip-validation to the commit message.

Q: Is my code being sent to an external LLM for review?

A: No. The analysis is entirely local and AST-based, ensuring 100% data sovereignty and zero API costs.

Rejected Alternatives

• Relying solely on human reviewers: Continuing to manually review and close low-substance PRs does not scale and exacerbates maintainer burnout.

• Restricting PR access to Collaborators Only: While GitHub recently introduced this feature to stop bot spam, using it heavily restricts legitimate, first-time open-source contributors from participating in Kafka.

• Using Third-Party GitHub Actions: Using pre-compiled external binaries for PR validation introduces supply-chain security risks and prevents developers from running the exact same checks locally on their laptops. Building it natively into our Gradle scripts solves both issues.

• Adding only AGENTS.md: A soft control that AI models probabilistically ignore. This KIP provides deterministic hard control.