The Lucene 10.6.0 release notes say StableTflSimilarity also supports k3, but 10.6.0 has no k3

The 10.6.0 New Features entry for GITHUB#16243 reads: "Add StableTflSimilarity, a similarity that estimates term rarity from term length and document length instead of corpus statistics such as document frequency. It also supports k3 query-term frequency saturation. (Tianxiao Wei)". The second sentence describes main (the future 11.0), not 10.6.0. The 10.6.0 class has only the (k1, c) and () constructors and no getK3(), and 10.6.0's Similarity lacks the computeQueryTermWeight hook that k3 needs. The 10.x backport #16322 left k3 out on purpose ("remove k3 which isn't in 10") and, at the feature author's request in review, dropped the sentence as well. A week later 3a75616c943, the 10.x backport of a test-only change (#16300), rewrote the entry back to main's wording in one of its CHANGES hunks. branch_10_6 inherited the sentence, 10.6.0 shipped with it (CHANGES.txt and the published Changes page), and main's copy of the 10.6.0 section has the same sentence. It is a documentation defect: nothing runs differently, and code written from the notes fails loudly at compile time. The fix is to delete the sentence from the 10.6.0 entry on main and branch_10_6.

• On main 645d4fe14a20, CHANGES.txt:456 is the Lucene 10.6.0 heading and CHANGES.txt:506-508 is the GITHUB#16243 entry ending "It also supports k3 query-term frequency saturation." The release 10.6.0 has the same text at CHANGES.txt:56-58, and the published 10.6.0 Changes page shows it.

• StableTflSimilarity.java at the 10.6.0 tag: the class javadoc lists only k1 and c (lines 45-49), @lucene.experimental (line 54), and the constructors (float k1, float c) (line 96) and () (line 117). There is no k3 field, constructor or getter.
• 10.6.0's Similarity has no computeQueryTermWeight, so no 10.6 similarity can apply k3.

• StableTflSimilarity.java on main: the javadoc bullet "k3 - query-side saturation for repeated query terms (disabled by default)" (line 50), DEFAULT_K3 = -1f (line 66), the (float k1, float c, float k3) constructor (line 110), computeQueryTermWeight with ((k3 + 1) * qtf) / (k3 + qtf) (lines 159-163) and getK3() (line 362).
• It overrides the main-only hook Similarity.computeQueryTermWeight (Similarity.java:175), which came with GITHUB#15818, listed in main's 11.0.0 section (CHANGES.txt:172, "Add BM25 k3 query-term frequency saturation to BM25Similarity").

1. 2026-07-01, main, e3a7a733c8a (#16243, txwei): the entry is written under main's 10.6.0 heading with the k3 sentence. True of main's class.
2. 2026-07-01, the #16322 review (the 10.x backport): on lucene/CHANGES.txt txwei asked to "remove the last part of supporting k3" and mccullocht replied "Done"; txwei also wrote "This major difference between the 10x backport and main is k3 is not supported on 10x".
3. 2026-07-01, branch_10x, 8e40c912555 (#16322): "remove k3 which isn't in 10". The entry ends "...such as document frequency. (Tianxiao Wei)". Correct.
4. 2026-07-08, branch_10x, 3a75616c943 (dweiss, "Backport changes to TestTermInSetQuery. #16300", pushed directly): its CHANGES diff adds the #16300 entry and, in a separate hunk, rewrites the #16243 entry's second line to main's wording, which brings the k3 sentence back. The message does not mention it.
5. 2026-10-14: branch_10_6 is cut from branch_10x and inherits it. The sentence survives the release manager's changelog clean-ups of 2026-10-20/21 (f79709fd57e, 7cecf795236), which do not touch this entry. 2026-10-26: RC1 4ae946e5a9b, released as 10.6.0.

• Who reads it: everyone who reads the 10.6.0 notes: CHANGES.txt in the source release, changes/Changes.html in the release folder, and the website's 10.6.0 Changes page.
• Who is hit: developers who adopt StableTflSimilarity on 10.6 and want k3. It is new in 10.6.0, not the default similarity, and @lucene.experimental.
• What they get: a compile error as soon as they try the advertised constructor or getK3(); someone who reads only the notes may plan for a feature that arrives in 11.0.
• What does not happen: no wrong results, no exception at run time, no index effect. Without k3 a repeated query term keeps its linear weight, which is normal 10.x behaviour.
• Scale: one sentence in one release line (10.6.x). On main the sentence is text only, since main's class has k3. The released 10.6.0 files stay as released; the fix corrects the 10.6.0 section that 10.6.1 and 11.0 will carry.

The test counts parameters only: on main the only 3-parameter constructor is (float k1, float c, float k3) (StableTflSimilarity.java:110), and 10.6.0 has none. Because it does not check the parameter types, the javac error, which names the exact (float,float,float) constructor and getK3(), is the stronger evidence. Reflection is used only so the same file compiles on both lines (10.6 and main); the user-facing symptom is the javac error of new StableTflSimilarity(1.2f, 0.917f, 7f), shown in the full output below. The result does not depend on the seed or on assertions.

No regression test applies. The fix is a CHANGES.txt edit. After it, this test still fails on branch_10_6 (the class correctly has no k3) and passes on main either way, so it is evidence, not a regression test.

cd $LUCENE && git checkout releases/lucene/10.6.0      # or branch_10_6
cp $REPRO/TestStableTflSimilarityK3.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/similarities/
./gradlew :lucene:core:test --tests org.apache.lucene.search.similarities.TestStableTflSimilarityK3 -Ptests.seed=DEADBEEF -Ptests.asserts=true
# same failure with -Ptests.asserts=false

# gradle on a worktree of releases/lucene/10.6.0 (4ae946e5a9b), seed DEADBEEF, -Ptests.asserts=true (identical with false)
TestStableTflSimilarityK3 > testK3ConstructorAdvertisedByChanges FAILED
    java.lang.AssertionError: expected StableTflSimilarity(k1, c, k3); actual: [public org.apache.lucene.search.similarities.StableTflSimilarity(float,float), public org.apache.lucene.search.similarities.StableTflSimilarity()]
:lucene:core:test (FAILURE): 1 test, 1  failure
BUILD FAILED

# released 10.6.0 jars (Maven Central, core sha1 9b71af62d7d3b5b99235187514a0d4d74817ccdd), standalone, -ea and -da: FAIL tests_run=1 failures=1, same message
# main 645d4fe14a20: PASS tests_run=1 failures=0 (main has k3)

# the user-facing symptom: javac of a two-line program against the same 10.6.0 jar (excerpt: path prefix, caret lines and javac's 'argument lists differ' / 'location' lines left out; every line shown is verbatim)
UseAdvertisedK3.java:8: error: no suitable constructor found for StableTflSimilarity(float,float,float)
    StableTflSimilarity sim = new StableTflSimilarity(1.2f, 0.917f, 7f);
    constructor StableTflSimilarity.StableTflSimilarity(float,float) is not applicable
    constructor StableTflSimilarity.StableTflSimilarity() is not applicable
UseAdvertisedK3.java:9: error: cannot find symbol
    System.out.println(sim + " k3=" + sim.getK3());
  symbol:   method getK3()
2 errors
# on main the same program compiles and prints: StableTflSimilarity(k1=1.2, c=0.917, k3=7.0) k3=7.0

• Removed on purpose. 8e40c912555 (#16322): "non-trivial integrations: symbol renames and remove k3 which isn't in 10". Review on lucene/CHANGES.txt: txwei, "remove the last part of supporting k3"; mccullocht, "Done". txwei, in a PR comment that says the changes LGTM: "This major difference between the 10x backport and main is k3 is not supported on 10x".
• Re-added, most likely by accident. 3a75616c943 (dweiss) backports a TestTermInSetQuery change (#16300) and has no PR of its own; besides adding the #16300 entry, one hunk of its CHANGES diff rewrites the #16243 entry's second line to main's wording, and its message does not mention #16243. Why is not recorded, so "by accident" is an inference.
• Release sections describe the release. dev-tools/scripts/diff_lucene_changes.py:24-29: keep main's and the stable branch's entries "identical and 2) matching what changes were actually backported to be honest to users". The 10.6 class javadoc itself lists only k1 and c.
• Precedent. Main's 10.6.0 section listed GITHUB#16794, which is not in 10.6.0; #16912 (mayya-sharipova, merged 2026-10-26, "Move CHANGES entry for GITHUB#16794 from 10.6.0 to 11.0.0") moved it.

Strongest case for leaving it: CHANGES is an informal summary; the authoritative 10.6 javadoc is correct; the sentence is literally true of main, where its author wrote it; the class is experimental; and the failure is a loud compile error that hurts no one, so it is a cosmetic nit.

Why it fails: it is not a wording slip but a false feature claim under the 10.6.0 heading, the exact claim the maintainers chose to drop for 10.x. Experimental status lets the API change between releases; it does not make the notes describe an API the release lacks. And the sentence is now on the published 10.6.0 Changes page and would be copied into every later CHANGES file. An independent reviewer from another model family (OpenAI GPT-5.6, reading only) rated the 'intended' argument weak; the earlier refute review's "not real" was procedural (it could not execute) and it called the evidence a genuine documentation discrepancy.

One CHANGES.txt edit, the same three lines on both branches. The released 10.6.0 files stay as they are; the fix shows from 10.6.1's and 11.0's CHANGES on. branch_10x needs nothing: it was decommissioned on 2026-10-29 (#16911). Optionally, main's 11.0.0 section can then say that StableTflSimilarity has k3 there.

Main's copy (CHANGES.txt:506-508 at 645d4fe14a20) and branch_10_6's (CHANGES.txt:56-58 at the 10.6.0 tag; today lines 63-65, below the new 10.6.1 section). The sibling LFV-957 (the 10.6.0 CheckIndex entry cites GITHUB#17820 instead of GITHUB#7820) is in the same section.

@@ -504,8 +504,7 @@
   enable with IndexWriterConfig#setMaxDocValuesOverlays(n). (Jim Ferenczi)
 
 * GITHUB#16243: Add StableTflSimilarity, a similarity that estimates term rarity from term length
-  and document length instead of corpus statistics such as document frequency. It also supports k3
-  query-term frequency saturation. (Tianxiao Wei)
+  and document length instead of corpus statistics such as document frequency. (Tianxiao Wei)
 
 * GITHUB#16371, GITHUB#14389: Add CaseFoldingFilter for Unicode simple case folding without
   requiring the ICU analysis plugin. Uses a generated switch for fold exceptions with

Trade-offs

None in code. After it, main's CHANGES.txt says nowhere that StableTflSimilarity has k3 (see the next option).

What the checks validated

In a scratch worktree of 645d4fe14a20 (OpenJDK 25.0.3): the diff applies and the 10.6.0 section then has no k3 line; the CHANGES-vs-release-jar text check (the 10.6.0 GITHUB#16243 entry against the released 10.6.0 core jar) fails on stock main's CHANGES.txt and passes on the fixed one, -ea and -da; ./gradlew :lucene:documentation:changesToHtml renders the entry without the sentence; :lucene:core:test with the repro and TestStableTflSimilarity passes, 15 tests, assertions on and off (main has k3, so this only shows nothing breaks). The branch_10_6 diff applies to the 2026-10-29 branch head with a 7-line offset.

A new 11.0.0 line, or extend the GITHUB#15818 entry (CHANGES.txt:172, "Add BM25 k3 query-term frequency saturation to BM25Similarity") to name StableTflSimilarity too. No CHANGES or MIGRATE.md text says today that k3 was left out of 10.6.

Trade-offs

Wording and placement are the committers' call; on main, StableTfl's k3 came with #16243 itself, so either placement needs a short explanation.

• Probe: a name-level check of all 39 Class#method and 129 class references in the RC's 10.6.0 section against the RC jars found no other missing API; javap of the RC core jar showed StableTflSimilarity with only (float,float) and (), and a probe calling new StableTflSimilarity(1.2f, 0.917f, 7f) ran on main and was a compile error on the RC.
• Finder (a hunt unit): a claim checker that reads a CHANGES file's 10.6.0 GITHUB#16243 entry and scans the release jar's class files (MISMATCH for the RC text and for main's 10.6.0 text against the RC jar; CONSISTENT for the fixed text and for main's text against main's jar), the git provenance (git log -S, blame), and a public-API JUnit test.
• Verification: an independent reproducer, an independent reviewer from another model family (OpenAI GPT-5.6) and an intended-behaviour devil's advocate all called it real; an adjudication confirmed it (high). The repro was then reduced to one test with one assertion.