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.

Rejected Alternatives

• Relying only on human reviewers: Does not scale. Maintainer time is the scarcest resource.

• Using third-party GitHub Actions: External binaries introduce supply-chain risk and cannot be run locally. Using buildSrc ensures developers run the exact same checks on their laptops (./gradlew checkContributionQuality).

• Extending Checkstyle only: Checkstyle operates per-file on the full source. It cannot measure per-PR logic density, nor can it easily enforce conditional architectural rules ("if file contains X, then block Y").

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

FAQ:

Q: Won't failing a CI check generate massive email spam to the dev@kafka mailing list? 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: 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: 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.

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.