The Lucene 10.6.0 documentation front page says "how to migrate code from Lucene 0.x": the build hands the major version to the page template as text, so "10" minus 1 becomes "0"

The front page of the 10.6.0 documentation (docs/index.html in the binary release, line 38) reads "What changed in Lucene 10; how to migrate code from Lucene 0.x." It should say 9.x, as 10.5.2 did. The template line is What changed in Lucene ${project.majorVersion}; how to migrate code from Lucene ${project.majorVersion-1}.x. (index.template.md:51-52), evaluated by Groovy's SimpleTemplateEngine. Since #14862 (main, 2025-07-01), and on the 10.x line since the build-infra backport #16592 (2026-09-05), the build's majorVersion is a String (LuceneBuildGlobalsExtension.java:51), and DocumentationConfigPlugin.java:233 binds it unchanged. For a String, Groovy's - removes the first occurrence of the operand's text: "10" - 1 is "0", "12" - 1 is "2". Through 10.5.2 the template called a closure that returned an int, ${project.majorVersion()-1}. Main builds print "Lucene 12; ... from Lucene 2.x.", branch_11x "Lucene 11; ... from Lucene 1.x.". Only this sentence is wrong: the link opens the correct Migration Guide and nothing in code, indexes or APIs changes. Binding Integer.parseInt(buildGlobals.majorVersion) restores "9.x" (main: "11.x"); the rebuilt page changes in that one line only.

• The 10.6.0 binary release's docs/index.html, line 38: <li><a href="MIGRATE.html">Migration Guide</a>: What changed in Lucene 10; how to migrate code from Lucene 0.x.</li>. 10.5.2's page has "... from Lucene 9.x." on the same line. The 10.6.0 website copy of the page is not published yet (HTTP 404 on 2026-11-02, while 10_6_0/MIGRATE.html is live).
• A build of main e1faeba08bde prints "What changed in Lucene 12; how to migrate code from Lucene 2.x."; branch_11x "Lucene 11; ... 1.x."; branch_10_6, the 10.6.1 line, "Lucene 10; ... 0.x.".

1. RegisterBuildGlobalsPlugin.java:149-152 returns the major version as the regex group of the version string, a String; :128 stores it: globals.majorVersion = majorVersion;. LuceneBuildGlobalsExtension.java:50-51: /** Major Lucene version ({@code x} in {@code x.y.z}). */ public String majorVersion;. A Gradle init script on the real build printed majorVersion=12 type=java.lang.String.
2. DocumentationConfigPlugin.java:227-233 binds it unchanged: Map.entry("majorVersion", buildGlobals.majorVersion) (line 234 at the 10.6.0 tag).
3. DocumentationConfigPlugin.java:331-336 evaluates the template with new SimpleTemplateEngine(); index.template.md:51-52: What changed in Lucene ${project.majorVersion}; how to migrate code from Lucene ${project.majorVersion-1}.x.
4. Groovy's String.minus(Object) removes the first "1": String "10" gives 0, "11" gives 1, "12" gives 2; Integer 10 gives 9, Integer 12 gives 11 (executed with Groovy 4.0.33, the version the main build's Gradle 9.8.1 ships, by checkers independently; a cross-model review got the same result for "11" and Integer 11 with Groovy 6.0.0 jars).

Through 10.5.2 the value came from an int closure (build.gradle:71: // "majorVersion" is an integer with just the major version. Compute it.; :77: return m[0][1] as int), and the template called ${project.majorVersion()-1}. The build has no other reader of buildGlobals.majorVersion at e1faeba08bde.

• Who meets it: anyone reading the documentation front page of the 10.6.0 binary release, or the website page if it is published from that build; a later 10.6.x or 11.x release built from the current branches before a fix would carry it too. The page is the documentation's entry page.
• What they get: a sentence naming a version that does not exist ("0.x", "1.x", "2.x"). The link next to it opens the correct guide, so nobody is sent to the wrong one.
• What does not happen: no effect on code, indexes, APIs, queries or results.
• Scale: one line of one generated page, but deterministic on every documentation build of the affected branches, and it would repeat for later majors while the value stays a String.
• How much it matters: little. The link works and readers will likely see "0.x" as a glitch. Still, it is a build-code regression (a type change in a refactor that expected no functional change), not a typo; it is in a released artifact; the fix is one line; and this page is already being fixed for 10.6.1 (#16939, #16941).

The test reads only page text, so the Lucene jars, the seed and -ea/-da cannot change the result; it uses no Lucene search or index API, only LuceneTestCase and its assertions, and the package only lets it run in :lucene:core:test. -Ptests.jvmargs passes the property 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 the build's checkLicenses would reject it in the tree.

The simplest demonstration needs no test: grep -n 'migrate code' lucene-10.6.0/docs/index.html prints line 38, "... how to migrate code from Lucene 0.x."; on main, run ./gradlew :lucene:documentation:createDocumentationIndex and grep lucene/documentation/build/site/index.html.

No regression test is suggested. The test needs a built page, so it does not fit gradlew test as it stands, and the fix is one line; it is evidence only. If committers want a guard, it is this same test.

cd $LUCENE                      # main, branch_11x or branch_10_6
./gradlew :lucene:documentation:createDocumentationIndex
cp $REPRO/TestMigrationGuidePreviousMajor.java lucene/core/src/test/org/apache/lucene/
./gradlew :lucene:core:test --tests org.apache.lucene.TestMigrationGuidePreviousMajor -Ptests.seed=DEADBEEF -Ptests.asserts=true "-Ptests.jvmargs=-Ddocs.dir=$PWD/lucene/documentation/build/site"
# same failure with -Ptests.asserts=false; for the released page: -Ddocs.dir=<unpacked lucene-10.6.0>/docs

# gradle on a worktree of main e1faeba08bde after createDocumentationIndex, seed DEADBEEF, -Ptests.asserts=true (identical with false)
> Task :lucene:core:test FAILED
TestMigrationGuidePreviousMajor > testPreviousMajor FAILED
    java.lang.AssertionError: expected:<11> but was:<2>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:3D9592C008903CD1]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.failNotEquals(Assert.java:835)
        at org.junit.Assert.assertEquals(Assert.java:647)
        at org.junit.Assert.assertEquals(Assert.java:633)
        at org.apache.lucene.TestMigrationGuidePreviousMajor.testPreviousMajor(TestMigrationGuidePreviousMajor.java:16)
:lucene:core:test (FAILURE): 1 test, 1  failure
BUILD FAILED in 51s

# the standalone JUnit runner, seed DEADBEEF
# 10.6.0 release docs/index.html   -ea FAIL expected:<9> but was:<0>    -da FAIL (same)
# main e1faeba08bde build          -ea FAIL expected:<11> but was:<2>   -da FAIL (same)
# 10.5.2 release docs/index.html   -ea PASS                             -da PASS
# main + fix (bind the int)        -ea PASS                             -da PASS

# the page line, main build before and after the fix
38c38
< <li><a href="MIGRATE.html">Migration Guide</a>: What changed in Lucene 12; how to migrate code from Lucene 2.x.</li>
---
> <li><a href="MIGRATE.html">Migration Guide</a>: What changed in Lucene 12; how to migrate code from Lucene 11.x.</li>

• The sentence and its arithmetic came with LUCENE-9321 (06df50e759a, "Port markdown task to Gradle (#1477)", Uwe Schindler, 2020-05-17, first released in 9.0.0), which added the template line ${project.majorVersion()-1} together with the int closure (// "majorVersion" is an integer with just the major version., return m[0][1] as int). Before that, the Ant build's index.xsl hard-coded the sentence for each major (since LUCENE-4008, a20aa3e0c99, 2012); LUCENE-9577 (2020-10-09) only moved the template.
• The build's own contract: 10.5.2 build.gradle:71: // "majorVersion" is an integer with just the major version. Compute it.; :77: return m[0][1] as int.
• History of the type (four steps; commit-level builds): through 10.5.2 majorVersion was a closure returning an int, called as ${project.majorVersion()-1}. #14764 (42123980c25, 2025-06-14) evaluated the closure eagerly, so it became an int property, and switched the template to the property form; harmless: a build of 6071569926f (#14879, the parent of #14862, which already has #14764's template and eager int) prints "Lucene 11; ... from Lucene 10.x.". #14862 (a7fc3d0ae83, 2025-07-01, "Gradle plugins to java, batch 1" by dweiss; PR description: "no functional changes are expected") introduced public String majorVersion; its build prints "... from Lucene 1.x.". #15350 (a0bd3c5f3c6) carried the String into the Java documentation task, and #16592 (f6fce7e42c5, 2026-09-05, a broad backport of main's build-infra changes) brought both to the 10.x line (parent "9.x", commit "0.x"). The searches found no discussion of the type or the sentence in these PRs.
• What the link covers: 10.6.0's MIGRATE.md:102 is "## Migration from Lucene 9.x to Lucene 10.0".
• No test or release check reads the sentence: no test in the main tree reads it, and the release smoke test only checks that the MIGRATE and CHANGES files exist.

Strongest case for leaving it (the intended-behaviour devil's advocate and the cross-model lenses): String is the declared type of the build global (javadoc "Major Lucene version ({@code x} in {@code x.y.z})"), Groovy's String.minus does exactly what it is documented to do, and the sentence is cosmetic: the link works.

Why it fails: the consumer is Lucene's own template, whose arithmetic only makes sense on a number and was written when the build documented the value as an integer; the String came from a refactor that expected no functional change; and "from Lucene 0.x" has no intended reading. Being cosmetic does not make it intended; it keeps the priority Low, while the false version still ships in a released artifact and comes from a build-code regression. An independent reviewer from another model family (OpenAI GPT-5.6) rated the "intended" case weak in both of its lenses.

One line in the documentation plugin (line 234 on branch_10_6). LFV-1087 is a second defect of the same front page (it lists benchmark-jmh javadocs that no build renders), and #16941 fixed a third one, the File Formats link, for 10.6.1. On main the fixed text "from Lucene 11.x" points at a MIGRATE.md section that does not exist yet (main's top section is "Migration from Lucene 10.x to Lucene 11.0"), which is normal before a major release.

DocumentationConfigPlugin.java:233 on main and branch_11x, :234 on branch_10_6 and the 10.6.0 tag.

@@ -230,7 +230,7 @@ public class DocumentationConfigPlugin extends LuceneGradlePlugin {
                   "project",
                   Map.ofEntries(
                       Map.entry("version", project.getVersion().toString()),
-                      Map.entry("majorVersion", buildGlobals.majorVersion)));
+                      Map.entry("majorVersion", Integer.parseInt(buildGlobals.majorVersion))));
 
           task.getBinding()
               .put(

Trade-offs

Smallest change; the build global keeps its String type. Integer.parseInt cannot fail for any real version: the \d+ regex group guarantees digits, and only a major above 2147483647 would overflow. Not applied to branch_10_6 here (same line text, one line lower).

What the checks validated

In a scratch worktree of main e1faeba08bde, OpenJDK 25.0.3, Gradle wrapper 9.8.1: createDocumentationIndex rebuilds the page, which differs from the stock build in line 38 only ("2.x" -> "11.x") and is byte-identical to the finder's fixed page; the minimal test through gradle passes with -Ptests.asserts=true and false (it fails on the stock page); ./gradlew :build-tools:build-infra-shadow:check, which re-applies Lucene's checks to the build-infra sources, passes (checkGoogleJavaFormat, ecjLint, forbiddenApisMain, checkLicenses, validatePlugins). Neither that project nor the documentation module has tests, so these are the closest checks. The worktree was removed afterwards.

index.template.md:52 becomes Lucene ${(project.majorVersion as int) - 1}.x.

Trade-offs

Fixes only this expression; any later template arithmetic on majorVersion hits the same trap, and the template is harder to read.

What the checks validated

Same scratch worktree, fix A reverted: the rebuilt page changes line 38 to "11.x" and the minimal test passes (-ea).

Declare public int majorVersion in LuceneBuildGlobalsExtension.java:51 and parse it once in RegisterBuildGlobalsPlugin.

Trade-offs

Restores the 10.5.2 contract ("an integer") for every consumer, but changes a public field of the build's extension and touches two files; at e1faeba08bde the documentation binding is its only reader.

• Lead: the hunt unit started from another defect on the same page (the API Javadocs list links benchmark-jmh, now LFV-1087) and swept the rest of the Groovy-to-Java port of the documentation build (gradle/documentation/*.gradle at 10.5.2 against DocumentationConfigPlugin.java, 15 items).
• Differential: the shipped 10.5.2 and 10.6.0 front pages differ in the Migration Guide sentence ("9.x" against "0.x").
• Build model: a Gradle init script printed the template binding on main, branch_11x and branch_10_6 (String every time) and on main with the fix (Integer).
• No model checker, SMT solver or prover was involved.