Skip to content

docs: document JDK 17 build requirement and Jabel Java 8 bytecode - #920

Open
Vishal Kumar Singh (singhvishalkr) wants to merge 1 commit into
confluentinc:masterfrom
singhvishalkr:docs-906-build-jdk-jabel
Open

docs: document JDK 17 build requirement and Jabel Java 8 bytecode#920
Vishal Kumar Singh (singhvishalkr) wants to merge 1 commit into
confluentinc:masterfrom
singhvishalkr:docs-906-build-jdk-jabel

Conversation

@singhvishalkr

@singhvishalkr Vishal Kumar Singh (singhvishalkr) commented May 8, 2026 •
edited
Loading

Copy link
Copy Markdown

Fixes #906.

Readers comparing
elease.target\ (8) with Mutiny were unsure how the tree compiles. The parent POM uses Java 17 sources with Jabel to emit Java 8 bytecode; IntelliJ activates a separate Maven profile.

Added a Development Information subsection in \src/docs/README_TEMPLATE.adoc\ and synced \README.adoc\ so GitHub shows it (Maven not available here to run \mvn process-sources; edits mirror what that goal emits).

Checklist

  • Documentation (if applicable)
  • Changelog

@singhvishalkr

Vishal Kumar Singh (singhvishalkr) commented May 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Only the Confluent CLA check is visible from this fork right now. Full GitHub Actions runs still need a maintainer to add the ok-to-test label, same as earlier PRs here. No further branch change from my side.

Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Jul 28, 2026
@astubbs @claude
docs: reconcile confluentinc#892 into confluentinc#859 + capture swee…
d02d185 
…p findings in manifest

The 2026-07-28 activity sweep surfaced upstream items the manifest didn't have.

Reconcile confluentinc#859: upstream PR confluentinc#892 (priesus) MERGED 2025-10-27 also targets the
PCMetrics leak, but fixes a DIFFERENT cause (OffsetMapCodecManager re-instantiated
each commit, recreating meters) than our fork fix (duplicate meter re-registration
on assign/revoke). Issue confluentinc#859 is still open, so mark upstream status 'mixed' and
add a reconciliation block tracking the open questions: does the fork already
carry confluentinc#892 / conflict with it, and did confluentinc#892 actually break the master build (the
author feared so; astubbs attributed it to the io.stubbs.truth dep not being on
Maven Central, not a code regression) -- verify before relying on it. Adds a
documented optional `reconciliation` field to the schema.

Capture other new findings: confluentinc#917 kafka-clients 3.9.2 SECURITY (into the security
batch); confluentinc#918/confluentinc#919 log-noise trims as a new logging-ux entry (with confluentinc#640/confluentinc#629/confluentinc#631);
confluentinc#920 JDK 17 build-doc PR linked to the Java-baseline entry; confluentinc#902 KEY-ordering
issue as a new entry; note confluentinc#921/confluentinc#922 (fork-awareness already partly upstream) on
the maintenance-signal entry so we don't duplicate it when backlinking.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Jul 28, 2026
@astubbs @claude
docs: durable upstream<->fork tracking cache + backlink/sweep tooling
a3c45b1 
Cache the fork<->upstream relationship once, machine-readably, so it stops being
re-derived by hand every session. This fork (bz.stub.parallelconsumer) tracks the
effectively-archived confluentinc/parallel-consumer, whose issues/PRs are a backlog
worth mining and back-linking.

Source of truth:
- src/docs/development/upstream-map.yaml -- one entry per unit of work mapping fork
  branch/PR <-> upstream issue/PR, work group, lifecycle status
  (none|in-progress|ready|pr-open|merged|released), optional reconciliation, todo,
  and a public-facing backlink message. Header documents the schema; carries a
  last_swept date. Design follows Debian DEP-3 / Yocto Upstream-Status / OpenShift
  UPSTREAM.
- src/docs/development/upstream-pr-analysis.adoc slimmed to editorial judgement
  (rankings/verdicts/merge order) with anchors the manifest links to; the manifest
  wins for facts. docs/inflight.md points at the manifest for the durable mapping.

Tooling (scripts/):
- upstream-map.py -- validate | table | refs | show | meta | tracked | posted-refs | todo
- upstream-backlink.sh -- post a "fixed in the fork" / "maintained in a fork" comment
  to an upstream issue/PR, driven by the manifest. Dry-run by default; anti-spam:
  idempotent (skips already-forwarded), per-run cap, delay, status guard. Comment
  body comes from the entry's backlink field (single source of truth) or a template.
- upstream-sweep.sh -- read-only check for NEW upstream activity since last_swept and
  drift on tracked refs; --publish updates a single fork tracking issue.

Conventions: .gitmessage adds DEP-3-style upstream commit trailers (unforced);
AGENTS.md documents the whole system.

Seeded from the analysis doc, inflight notes, git and memory, and reconciled against
a live gh sweep -- which caught drift (upstream confluentinc#541/confluentinc#548 now closed, confluentinc#866 is Kafka
v4 not v7) and new items (confluentinc#892 merged, confluentinc#917/confluentinc#918/confluentinc#919/confluentinc#920/confluentinc#902). confluentinc#859 reconciled:
upstream confluentinc#892 fixed the per-commit meter churn; fork PR #57 fixes the tracking-List
(List->Set) plus assignment-path OffsetMapCodecManager caching.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Jul 28, 2026
@astubbs @claude
docs: durable upstream<->fork tracking cache + backlink/sweep tooling
c231d70 
Cache the fork<->upstream relationship once, machine-readably, so it stops being
re-derived by hand every session. This fork (bz.stub.parallelconsumer) tracks the
effectively-archived confluentinc/parallel-consumer, whose issues/PRs are a backlog
worth mining and back-linking.

Source of truth:
- src/docs/development/upstream-map.yaml -- one entry per unit of work mapping fork
  branch/PR <-> upstream issue/PR, work group, lifecycle status
  (none|in-progress|ready|pr-open|merged|released), optional reconciliation, todo,
  and a public-facing backlink message. Header documents the schema; carries a
  last_swept date. Design follows Debian DEP-3 / Yocto Upstream-Status / OpenShift
  UPSTREAM.
- src/docs/development/upstream-pr-analysis.adoc slimmed to editorial judgement
  (rankings/verdicts/merge order) with anchors the manifest links to; the manifest
  wins for facts. docs/inflight.md points at the manifest for the durable mapping.

Tooling (scripts/):
- upstream-map.py -- validate | table | refs | show | meta | tracked | posted-refs | todo
- upstream-backlink.sh -- post a "fixed in the fork" / "maintained in a fork" comment
  to an upstream issue/PR, driven by the manifest. Dry-run by default; anti-spam:
  idempotent (skips already-forwarded), per-run cap, delay, status guard. Comment
  body comes from the entry's backlink field (single source of truth) or a template.
- upstream-sweep.sh -- read-only check for NEW upstream activity since last_swept and
  drift on tracked refs; --publish updates a single fork tracking issue.

Conventions: .gitmessage adds DEP-3-style upstream commit trailers (unforced);
AGENTS.md documents the whole system.

Seeded from the analysis doc, inflight notes, git and memory, and reconciled against
a live gh sweep -- which caught drift (upstream confluentinc#541/confluentinc#548 now closed, confluentinc#866 is Kafka
v4 not v7) and new items (confluentinc#892 merged, confluentinc#917/confluentinc#918/confluentinc#919/confluentinc#920/confluentinc#902). confluentinc#859 reconciled:
upstream confluentinc#892 fixed the per-commit meter churn; fork PR #57 fixes the tracking-List
(List->Set) plus assignment-path OffsetMapCodecManager caching.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Jul 28, 2026
@astubbs @claude
docs: durable upstream<->fork tracking cache + backlink/sweep tooling
e1d083b 
Cache the fork<->upstream relationship once, machine-readably, so it stops being
re-derived by hand every session. This fork (bz.stub.parallelconsumer) tracks the
effectively-archived confluentinc/parallel-consumer, whose issues/PRs are a backlog
worth mining and back-linking.

Source of truth:
- src/docs/development/upstream-map.yaml -- one entry per unit of work mapping fork
  branch/PR <-> upstream issue/PR, work group, lifecycle status
  (none|in-progress|ready|pr-open|merged|released), optional reconciliation, todo,
  and a public-facing backlink message. Header documents the schema; carries a
  last_swept date. Design follows Debian DEP-3 / Yocto Upstream-Status / OpenShift
  UPSTREAM.
- src/docs/development/upstream-pr-analysis.adoc slimmed to editorial judgement
  (rankings/verdicts/merge order) with anchors the manifest links to; the manifest
  wins for facts. docs/inflight.md points at the manifest for the durable mapping.

Tooling (scripts/):
- upstream-map.py -- validate | table | refs | show | meta | tracked | posted-refs | todo
- upstream-backlink.sh -- post a "fixed in the fork" / "maintained in a fork" comment
  to an upstream issue/PR, driven by the manifest. Dry-run by default; anti-spam:
  idempotent (skips already-forwarded), per-run cap, delay, status guard. Comment
  body comes from the entry's backlink field (single source of truth) or a template.
- upstream-sweep.sh -- read-only check for NEW upstream activity since last_swept and
  drift on tracked refs; --publish updates a single fork tracking issue.

Conventions: .gitmessage adds DEP-3-style upstream commit trailers (unforced);
AGENTS.md documents the whole system.

Seeded from the analysis doc, inflight notes, git and memory, and reconciled against
a live gh sweep -- which caught drift (upstream confluentinc#541/confluentinc#548 now closed, confluentinc#866 is Kafka
v4 not v7) and new items (confluentinc#892 merged, confluentinc#917/confluentinc#918/confluentinc#919/confluentinc#920/confluentinc#902). confluentinc#859 reconciled:
upstream confluentinc#892 fixed the per-commit meter churn; fork PR #57 fixes the tracking-List
(List->Set) plus assignment-path OffsetMapCodecManager caching.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Aug 6, 2026
@astubbs @claude
ci: gate TODO-index staleness, and stop recording numbers that go stale
1f862a4 
Two changes, one idea: a number written down cannot notice when it stops
being true.

bin/todo-index.sh --check now runs in the PR Checklist job. It was never
wireable before, because entries were keyed by line number and any edit
above a marker churned the file - it would have failed PRs that never
touched a marker. Text keying made the gate fair.

Adding it caught itself immediately. The step was named "Verify the TODO
index matches the tree", the scanner reads .yml, so the step name
registered as a marker and made the index stale. Renamed to "marker
index" rather than blunting the scanner, which was right.

Then the numbers. Four drifts on this PR were all one shape: a count
written in a file that cannot see what it counts. "three files are
exempt" beside an array in another file; "15 assertions" beside a test
file in a third. Each was true when written, and none had any way to
learn otherwise. They are replaced by the means to regenerate them:

- "Four files are exempt" -> "the files listed in EXEMPT_PATHS"
- the reference-backlog totals -> the node snippet that counts them,
  since the backlog shrinks as the sweep runs
- confluentinc's numbering headroom -> the gh query that measures it

Writing that query out found a bug in it. The obvious form defaults to
state=open and reports confluentinc#920; the real ceiling is confluentinc#922, a merged PR. A
number copied from the wrong query would have been quietly wrong and
unfalsifiable. A command is at least checkable, which is the argument in
miniature.

Historical figures stay - "48 of 51 numbers existed in both repos" is a
measurement of a moment, not a live value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QqHpNSXC39ANv9kG1ZvUzn
@astubbs Antony Stubbs (astubbs) mentioned this pull request Sep 18, 2026
Merged
6 tasks done
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Sep 18, 2026
@astubbs @claude
docs(upstream) confluentinc#920: the manifest entry names its PR
a3649e1 
The carry opened as #519, so the entry moves from ready to
pr-open with the number, in the same change as the PR per docs/upstream.md.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XS64Xttx4vF5datYh7fmk
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Sep 18, 2026
@astubbs @claude
docs(upstream) confluentinc#920: the manifest entry lands in its merg…
16e7508 
…ed state

The squash of this branch is the lifecycle transition, so the entry it
carries must already read merged when it lands - branches cleared, the
PR number kept - rather than pr-open with a follow-up nobody makes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XS64Xttx4vF5datYh7fmk
Antony Stubbs (astubbs) added a commit to astubbs/parallel-consumer that referenced this pull request Sep 18, 2026
@astubbs @claude
docs(readme) confluentinc#920: the README says a build needs JDK 17, …
542b093 
…and why the jar is still Java 8 (#519)

What a reader could not find before: the README said the library runs on
Java 8 and that the Mutiny module needs Java 17 at runtime, but nowhere
said that BUILDING from source needs JDK 17. That fact lived only in
AGENTS.md, docs/building.md and the pom, so a contributor comparing
release.target (8) with the Mutiny dependency concluded the tree could
not compile for anyone (confluentinc#906, fork mirror #194).

What the new "Build JDK and bytecode level" subsection says, under
Development Information next to the build requirements:

- Building needs JDK 17: the enforcer's requireJavaVersion rule rejects
  anything below source.version, and JDK 21 or newer fails the other
  way because Jabel 1.0.0's bundled Byte Buddy refuses class-file
  version 65. CI builds on Temurin 17. It links the solution write-up
  that measured this.
- source.version is 17 and release.target is 8: Java 17 source is
  compiled to Java 8 bytecode by the Jabel javac plugin with
  --release 8, which is why the jar runs on Java 8 while its source
  does not compile there.
- The Mutiny module is the exception: SmallRye Mutiny is built for
  Java 17 and implements java.util.concurrent.Flow, so that module
  overrides release.target to 17 and emits Java 17 bytecode, matching
  its runtime floor. Core, Vert.x and Reactor stay at Java 8.
- IntelliJ IDEA activates the intellij-idea-only profile, which compiles
  at source.version throughout and drops Jabel from the annotation
  processors; plain mvn uses Jabel with --release 8.
- Surefire and Failsafe fork ${jvm.location}/bin/java, defaulting to
  ${java.home}; the jvm8-release and jvm9-release profiles repoint it,
  and the pom marks jvm8-release as currently broken.
- The fresh-clone recipe and the generated-Truth trap stay owned by
  docs/building.md and the Maven targets section; the subsection links
  them rather than restating them.

Provenance and credit: the subsection is carried from upstream PR
confluentinc#920, "docs: document JDK 17 build
requirement and Jabel Java 8 bytecode", by Vishal Kumar Singh
(singhvishalkr), which fixes confluentinc#906 and is still open
upstream. The structure and most of the claims are his.

Where the wording departs from the upstream text, and why, verified
against this tree's pom.xml:

- Upstream says "JDK 17 or newer". Here it is JDK 17 specifically: the
  requireJavaVersion rule is [${source.version},) as upstream says, but
  Jabel 1.0.0 cannot load on JDK 21 (pom comment on error-prone.version;
  docs/solutions/build-errors/error-prone-jabel-and-the-jdk-that-
  satisfies-neither-2026-08-25.md), and every CI workflow pins
  Temurin 17.
- Upstream says Mutiny's Java-17 APIs are fine because "Jabel is what
  targets Java 8 bytecode for project sources". That was the upstream
  state; this fork's Mutiny module overrides release.target to 17
  (#214), so the subsection describes the override and points
  at the per-module Java table instead.
- Upstream says the IDE profile "raises release and target to match
  source.version". The profile also replaces the annotation-processor
  list with Lombok alone, disabling Jabel, and the text now says so.
- Upstream names jvm8-release as a working option; the pom marks it
  "currently broken", and jvm9-release exists beside it, so both are
  named with that caveat.
- Property and profile names checked present in pom.xml:
  source.version, release.target, jvm.location, jvm8.location,
  jvm9.location, intellij-idea-only, jvm8-release, jvm9-release,
  requireJavaVersion, jabel-javac-plugin, and the surefire/failsafe
  <jvm> elements.

AGENTS.md's Build Requirements and docs/building.md were cross-checked
and already agree (JDK 17, Jabel, the Mutiny override); neither needed
a change and neither restates the README text.

README.adoc is regenerated from src/docs/README_TEMPLATE.adoc with
mvnw -N asciidoc-template:build. src/docs/development/upstream-map.yaml
gains a docs-920-build-jdk-requirement entry (status merged, PR #519, carried on branch
docs/920-jdk17-build-requirement) and moves 920 from
java-17-baseline-kafka4's primary PRs to its related list, since that
entry is about moving the baseline and this one documents the baseline
that exists.

Upstream-Issue: confluentinc#906
Upstream-PR: confluentinc#920
Forwarded: not-needed
Applied-Upstream: no

Co-authored-by: Claude Fable 5.1 (1M context) <noreply@anthropic.com>
@astubbs

Antony Stubbs (astubbs) commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Vishal Kumar Singh (@singhvishalkr) - this is merged in the maintained fork, with credit to you: astubbs#519, landed on master as 542b0939c, "the README says a build needs JDK 17, and why the jar is still Java 8". It will be in the README of the next release; the v0.6.0.0 README predates it. Two corrections on the way, each verified against the fork's pom: it is JDK 17 specifically, not "17 or newer", since JDK 21 and later fail on Jabel's bundled Byte Buddy; and the Mutiny module overrides its release level to 17 rather than relying on Jabel. Thank you for writing it; the fork is where the work continues.

The coordinates changed with the fork - on Maven Central it is now:

<dependency>
    <groupId>bz.stub.parallelconsumer</groupId>
    <artifactId>parallel-consumer-core</artifactId>
    <version>0.6.0.0</version>
</dependency>

(parallel-consumer-vertx, parallel-consumer-reactor and parallel-consumer-mutiny likewise.) The Java package is bz.stub.parallelconsumer too, so imports change with it - one command rewrites them (GNU sed; on macOS use sed -i ''):

find . -name '*.java' -exec sed -i 's/io\.confluent\.parallelconsumer/bz.stub.parallelconsumer/g' {} +

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Mismatch between release.version in pom.xml and dependencies

2 participants

@singhvishalkr @astubbs