The documentation front page links benchmark-jmh javadocs that no build renders

The documentation front page (docs/index.html) has an "API Javadocs" list with one link per module. In 10.6.0 it lists 32 modules; 10.5.2 listed 31. The extra entry, benchmark-jmh/index.html on line 59, leads to a page that a standard documentation build does not write: lucene/benchmark-jmh/build.gradle disables the module's renderSiteJavadoc task on purpose, and the 10.6.0 binary archive has no docs/benchmark-jmh/ folder.

The list comes from MarkdownTemplateTask.withProjectList() in DocumentationConfigPlugin. Its javadoc says it lists "all subprojects with javadocs", but its filter keeps every :lucene subproject that has a task named renderSiteJavadoc, enabled or not. The Groovy version it replaced (up to 10.5.2) kept only subprojects whose task is enabled. #15350 dropped that check when it moved the documentation scripts to Java (main, 2025-10-22); the backport #16592 brought it into 10.6.0. benchmark-jmh has the task at all only because its exclusion from the published projects is spelled :lucene:benchmarks-jmh, so it never matches; until the port the enabled filter hid that.

It is a documentation defect only: code, APIs and indexes are not affected. The fix is one condition, && t.getEnabled(), which removes exactly the benchmark-jmh line.

1. DocumentationConfigPlugin.java:256: createDocumentationIndex calls task.withProjectList(), which fills ${projectList} under "## API Javadocs" in lucene/documentation/src/markdown/index.template.md:65-67.
2. DocumentationConfigPlugin.java:344-347, the method's javadoc: adds a property "projectList" containing all subprojects with javadocs as markdown bullet list.
3. DocumentationConfigPlugin.java:355-363, the filter: .filter(p -> p.getTasks().matching(t -> t.getName().equals("renderSiteJavadoc")).stream().findAny().isPresent()). It checks that the task exists, not that it is enabled. Lines 370-385 turn each kept module into **[name](path/index.html):** description.
4. RenderJavadocPlugin.java:143-150 registers renderSiteJavadoc for every published project except :lucene:luke; it writes to the documentation root plus the module path (:180-185).
5. RegisterBuildGlobalsPlugin.java:111-115 excludes ":lucene:misc:native", ":lucene:spatial-test-fixtures", ":lucene:benchmarks-jmh" from the published projects. The module is lucene:benchmark-jmh (settings.gradle:67), so the exclusion never matches and the module gets the task.
6. lucene/benchmark-jmh/build.gradle:40-49 disables renderSiteJavadoc and renderJavadoc ("// No special javadocs for JMH benchmarks.", it.enabled = false). The task is SKIPPED and writes nothing.
7. The Groovy original, 10.5.2 gradle/documentation/markdown.gradle:152-155, same javadoc: def projects = productProject.subprojects.findAll{ it.tasks.findByName('renderSiteJavadoc')?.enabled }.

A Gradle build model over all 32 :lucene subprojects that have the task: listed 32, rendered 31, listed-not-rendered [benchmark-jmh], rendered-not-listed [], on main, branch_11x and branch_10_6. benchmark-jmh is the only module with the task disabled, so it is the only wrong entry.

• Who sees it: readers of docs/index.html in the 10.6.0 binary release and of every documentation build of main, branch_11x and branch_10_6 (the 10.6.1 line). The 10.6.0 site copy was committed to the site repository on 2026-10-30 with the same line and no benchmark-jmh/ folder; https://lucene.apache.org/core/10_6_0/index.html still returned 404 on 2026-11-02, so the dead link goes live when that copy is served.
• Default, not opt-in: the standard documentation build produces it; no setting or input is involved.
• Scale: one of 32 module links. A check of all 46 relative links of the shipped 10.6.0 front page against the archive finds exactly two missing targets: this one and the File Formats link of #16939 (already fixed by #16941). 10.5.2: 45 relative links, none missing.
• Severity: low. The entry is the javadoc page of an internal micro-benchmark module with no API that users code against, and the failure is a plain "page not found".
• Release line: branch_10_6 (the 10.6.1 line) still has it, while the related fix #16941 was backported there.

No Lucene API is involved, so the documentation tree passed in decides the result; the seed and -ea/-da cannot change it. The package only gives the file a home in lucene/core's tests. -Ptests.jvmargs passes the path to the forked test JVM (it replaces gradle's default extra test JVM flags, which does not matter here). The file has no Apache license header, so check would fail in checkLicenses with it in the tree.

For the 10.6.0 release, point docs.dir at the extracted lucene-10.6.0/docs: same failure. The 10.5.2, 10.0.0 and 9.12.3 release docs pass. The 10.6.0 and 10.5.2 runs read the release's index.html plus its module index pages, taken from the sha512-verified archive (everything this test reads); the 10.0.0 and 9.12.3 runs read full docs/ trees.

No regression test is suggested for Lucene's suite: the check needs a built documentation tree, which unit tests do not have. If maintainers want a guard, it is this same check run on the built site, or the link checker whose loss Uwe Schindler noted on #16939.

cd $LUCENE      # main, branch_11x or branch_10_6
./gradlew :lucene:documentation:documentation
cp $REPRO/TestFrontPageJavadocLinks.java lucene/core/src/test/org/apache/lucene/
./gradlew :lucene:core:test --tests org.apache.lucene.TestFrontPageJavadocLinks -Ptests.seed=DEADBEEF -Ptests.asserts=true "-Ptests.jvmargs=-Ddocs.dir=$PWD/lucene/documentation/build/site"
# same failure with -Ptests.asserts=false

# gradle on a scratch worktree of main e1faeba08bde, seed DEADBEEF, -Ptests.asserts=true (identical with false)
> Task :lucene:core:test FAILED
TestFrontPageJavadocLinks > testListedModuleJavadocsExist FAILED
    java.lang.AssertionError: expected:<[]> but was:<[benchmark-jmh/index.html]>
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.failNotEquals(Assert.java:835)
        at org.junit.Assert.assertEquals(Assert.java:120)
        at org.junit.Assert.assertEquals(Assert.java:146)
        at org.apache.lucene.TestFrontPageJavadocLinks.testListedModuleJavadocsExist(TestFrontPageJavadocLinks.java:21)
:lucene:core:test (FAILURE): 1 test, 1  failure
BUILD FAILED

# the documentation build it ran on
> Task :lucene:benchmark-jmh:renderSiteJavadoc SKIPPED        (the other 31 renderSiteJavadoc tasks ran)
index.html:59  <li><strong><a href="benchmark-jmh/index.html">benchmark-jmh</a>:</strong> Lucene JMH micro-benchmarking module</li>
site top level: no benchmark-jmh/ entry

# the same test through the standalone JUnit runner, seed DEADBEEF (the test has no randomness)
# main e1faeba08bde docs build: FAIL 1/1 with -ea and -da; with the fix, rebuilt: PASS with -ea and -da
# 10.6.0 release docs (index.html + module index pages): FAIL 1/1 with -ea and -da (line 59 is identical; the archive has no docs/benchmark-jmh/)
# 10.5.2 release docs (same subset), 10.0.0 and 9.12.3 release docs: PASS with -ea and -da

• The contract: DocumentationConfigPlugin.java:345: "all subprojects with javadocs". benchmark-jmh/build.gradle:43: "No special javadocs for JMH benchmarks."
• Disabling the task is how a module leaves the site. PR #120 (LUCENE-9947): "This excludes Javadocs of luke module from the documentation site by explicitly disable \"renderSiteJavadoc\" task for it. While removing the link to javadocs, ...". The Groovy ?.enabled filter (since LUCENE-9321, 06df50e759a, 2020) is what made that work.
• A port, not a redesign. #15350 and #16592 carried over the link format, descriptions, core styling and sort keys, minus one dead sort key (the Groovy sort also put a solrj module right after core, 10.5.2 markdown.gradle:157; Lucene has no such module). The only change to which modules are listed is the dropped ?.enabled. No PR text, commit message, CHANGES or MIGRATE entry mentions which modules are listed.
• No test covers it, and, as Uwe Schindler pointed out on #16939, #14905 removed the link checker, so "the markdown files on top level were no longer checked for incorrect links". That is why it went unnoticed, not the defect.
• Precedent: #16939 ("We should fix this, but respin not needed."), the wrong File Formats link on the same page from the same port, fixed by #16941 and backported to branch_10_6.

Strongest case for "intended": the port redefined "rendered" as "has the task". In the Java build luke is kept off the site by not registering the task at all (RenderJavadocPlugin.java:145), and #15350 allowed "some minor tweaks here and there". A second reading: the real cause is the old :lucene:benchmarks-jmh typo.

Why it fails: the method's javadoc still says "with javadocs", benchmark-jmh's build still disables the task to keep its javadocs out, nothing announces a change, and no reading makes a link to a folder the same build never writes intended. The typo dates from 10.0.0 and was harmless to the front page until the port dropped the filter (10.0.0 and 10.5.2 list 31 modules); it offers a second fix site, not an intended behaviour.

One condition in the build tooling restores what the Groovy build did. The alternative, correcting the benchmarks-jmh spelling, would also change what is published, so it is a separate question.

DocumentationConfigPlugin.java:360 on main e1faeba08bde and on branch_11x, line 368 on branch_10_6; the same diff applies to both (git apply places the hunk 8 lines lower on branch_10_6). It restores the Groovy semantics and matches the method's javadoc.

@@ -357,7 +357,10 @@
                                 p ->
                                     p
                                         .getTasks()
-                                        .matching(t -> t.getName().equals("renderSiteJavadoc"))
+                                        .matching(
+                                            t ->
+                                                t.getName().equals("renderSiteJavadoc")
+                                                    && t.getEnabled())
                                         .stream()
                                         .findAny()
                                         .isPresent())

Trade-offs

None seen in the recorded builds. The enabled flag is set while the build is configured (configureEach in benchmark-jmh/build.gradle); the list is computed later, when createDocumentationIndex resolves its binding, so the check sees the final value, as the regenerated page shows. Like the Groovy ?.enabled, getEnabled() reads only that flag: an enabled task skipped for another reason (an onlyIf condition, say) would still be listed. On main today that changes nothing: with the fix, listed = rendered = 31 in the build model.

What the checks validated

In scratch worktrees of e1faeba08bde, OpenJDK 25.0.3, 2026-11-02:

• stock: :lucene:documentation:documentation succeeds, benchmark-jmh's task is SKIPPED, no folder, link on line 59; the minimal test fails through gradle (assertions on and off) and the standalone JUnit runner (-ea, -da);
• with the diff: the rebuilt index.html differs from stock by exactly the removed benchmark-jmh line; the site's top-level listing is identical; the minimal test passes through gradle (assertions on and off) and the standalone JUnit runner (-ea, -da);
• ./gradlew :build-tools:build-infra-shadow:check with only the diff applied: BUILD SUCCESSFUL (compile, checkGoogleJavaFormat, ecjLint, forbiddenApis, validatePlugins, checkLicenses). build-infra has no test sources, so the rebuild plus the minimal test is the functional check.
• The finder and an independent reproducer got the same one-line page difference on their own builds.

RegisterBuildGlobalsPlugin.java:114. benchmark-jmh would then get no renderSiteJavadoc task and drop off the list.

Trade-offs

It also makes benchmark-jmh unpublished: lucene-benchmark-jmh, on Maven Central for 10.0.0 to 10.6.0, would stop being published, and the binary distribution's modules/ would change. Whether that artifact should be published is a separate question for maintainers, and the filter would stay wrong for any other module that disables the task.

#14905 removed it, as Uwe Schindler noted on #16939.

Trade-offs

Would have caught this and #16939, but it is a larger change than this bug needs; a guard, not the fix.

• First signal: a lead that took up Uwe Schindler's remark on #16939 (#14905 removed the link checker for the top-level pages) compared withProjectList with the Groovy filter and saw the benchmark-jmh entry in a createDocumentationIndex build of main and in the 10.6.0 release docs.
• Re-derived by a hunt unit: a Gradle init script over the real build computed the listed and the rendered modules for all 32 :lucene subprojects that have the task (listed minus rendered = [benchmark-jmh], rendered minus listed = [], on main, branch_11x and branch_10_6); all 46 relative links of the shipped 10.6.0 front page were checked against the archive listing (2 missing: this one and #16939's); a line-by-line comparison of the Groovy documentation scripts with the Java port found one more defect on the same page, the Migration Guide line naming Lucene "0.x".
• Verification: an independent reproducer ran a full documentation build of main, an independent reviewer from another model family (OpenAI GPT-5.6) ran a refute lens and an intended lens, and an intended-behaviour devil's advocate searched for a reason it could be intended; all called it real, and an adjudication confirmed it (high). The repro was then reduced to one test with one assertion.