TemporalMergePolicy's javadoc configuration example calls setBaseTimeSeconds, a method that does not exist

The finding in 30 seconds

The example sits in a plain <pre> block of the class javadoc. Javadoc does not compile such blocks, so when the setter was renamed nothing failed, and Lucene's own tests use the new name.

You adopt the time-series merge policy added in Lucene 10.5 and copy the "Configuration:" example from its class javadoc: new TemporalMergePolicy().setTemporalField("timestamp").setBaseTimeSeconds(3600).setMinThreshold(4).setMaxThreshold(8).setCompactionRatio(1.2).
You expect it to compile and give a policy with a 1-hour (3600 s) base window, thresholds 4 and 8 and compaction ratio 1.2, as its comments say.
Instead javac stops with one error: cannot find symbol: method setBaseTimeSeconds(int). The class has no such method; its setter is setBaseTimeInSeconds(long), about 100 lines further down the same file.
The setter was renamed on a reviewer's suggestion while the feature was in review; a commit the same day edited the example three lines below and left this line alone. With setBaseTimeInSeconds(3600) the example compiles and sets exactly the commented values.

Who is affected

Developers adopting the opt-in, experimental TemporalMergePolicy who start from its only configuration example: they get one compile error every time, on 10.5.0 to 10.6.0 and main. Documentation only: nothing in Lucene runs differently, and the error names the missing method.

Mechanism, terms and numbers354 words

TemporalMergePolicy (new in 10.5.0, @lucene.experimental) groups segments into time windows for time-series data. Its class javadoc has one "Configuration:" example, a fluent chain setTemporalField("timestamp"), .setBaseTimeSeconds(3600), .setMinThreshold(4), .setMaxThreshold(8), .setCompactionRatio(1.2), followed by IndexWriterConfig.setMergePolicy(policy). The class has no setBaseTimeSeconds method: its base-time setter is setBaseTimeInSeconds(long). Copied into a project, the example fails with the single javac error cannot find symbol: method setBaseTimeSeconds(int), location: class org.apache.lucene.index.TemporalMergePolicy, on 10.5.0, 10.5.1, 10.5.2, 10.6.0 and main. In PR #15620 the setter first had the old name and the example matched; a reviewer suggested the clearer name, the rename went in, and the example kept the old one. With setBaseTimeInSeconds(3600) the example compiles and configures exactly what its comments say. Nothing in Lucene behaves wrongly; only the example is stale.

The example (main `645d4fe14a20`)

line	text	exists?
59	`TemporalMergePolicy policy = new TemporalMergePolicy()`	yes
60	`.setTemporalField("timestamp")`	yes, `setTemporalField(String)` (line 128)
61	`.setBaseTimeSeconds(3600) // Base window size: 1 hour`	no
62-64	`.setMinThreshold(4)`, `.setMaxThreshold(8)`, `.setCompactionRatio(1.2)`	yes, `int` (187), `int` (245), `double` (281)
65	comment: "By default, exponential buckets are enabled. Use .disableExponentialBuckets() to disable."	yes (220)
67-68	`new IndexWriterConfig(analyzer)`, `config.setMergePolicy(policy)`	yes

The real setter

public TemporalMergePolicy setBaseTimeInSeconds(long baseTimeInSeconds) (line 159), documented "Default is 3600 seconds (1 hour)." Its getter getBaseTimeInSeconds() (line 172) carries @see #setBaseTimeInSeconds. In Lucene's sources the name setBaseTimeSeconds occurs only on line 61, on main and at every release tag that has the class (10.5.0 to 10.6.0). A bytecode scan of 159 core jars finds that the class declares no setBaseTimeSeconds of any arity in any release, and javac finds no inherited one either.

Why nothing caught it

Javadoc does not compile <pre class="prettyprint"> blocks, and the example has no {@link} that javadoc would check. Lucene's tests use the real name: TestTemporalMergePolicy.testMergesWorkWithUncommittedSegments calls .setBaseTimeInSeconds(3600) in a chain of its own, with other values (field timestamp_tl, thresholds 3 and 4, ratio 1.0).

Not claimed

The private field baseTimeSeconds (line 102) and the exception text "baseTimeSeconds must be positive" (line 161) still use the old name; neither is public API. The undeclared analyzer is normal for a fragment.

Exposure and likelihood101 words

Who. Readers of the TemporalMergePolicy class javadoc who copy its example. No query, document or index file reaches it.
Default vs opt-in. The policy is opt-in (set on IndexWriterConfig by the application) and @lucene.experimental. No configuration or special input is involved: the copied example always fails.
Scale. One error on every release that has the class: 10.5.0, 10.5.1, 10.5.2 and 10.6.0, and on main.
Effect. A compile error, not wrong behaviour. The right name is setBaseTimeInSeconds, listed in the same javadoc page.
Priority. Low; the same kind of defect as the stale javadoc examples LFV-1018, LFV-1019, LFV-1021 and LFV-1026.

Minimal repro

One JUnit class with one test. It compiles the javadoc example, copied verbatim, with javax.tools against the jars on the test class path; it adds only the imports, an enclosing class and the analyzer parameter the example leaves undeclared. Nothing in Lucene runs, and nothing is random.

TestTemporalMergePolicyJavadocExample.java (one test, public API)70 lines

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.index;

import java.net.URI;
import java.util.List;
import javax.tools.DiagnosticCollector;
import javax.tools.JavaFileObject;
import javax.tools.SimpleJavaFileObject;
import javax.tools.ToolProvider;
import org.apache.lucene.tests.util.LuceneTestCase;

public class TestTemporalMergePolicyJavadocExample extends LuceneTestCase {

  // Expected: the TemporalMergePolicy class-javadoc example compiles; actual: javac cannot find setBaseTimeSeconds(int).
  public void testClassJavadocExampleCompiles() throws Exception {
    String source =
        """
        import org.apache.lucene.analysis.Analyzer;
        import org.apache.lucene.index.IndexWriterConfig;
        import org.apache.lucene.index.TemporalMergePolicy;
        class Example {
          void example(Analyzer analyzer) {
        TemporalMergePolicy policy = new TemporalMergePolicy()
            .setTemporalField("timestamp")           // Required: name of the timestamp field
            .setBaseTimeSeconds(3600)                // Base window size: 1 hour
            .setMinThreshold(4)                      // Merge when 4+ segments in a window
            .setMaxThreshold(8)                      // Merge at most 8 segments at once
            .setCompactionRatio(1.2);                // Size ratio threshold for merging
            // By default, exponential buckets are enabled. Use .disableExponentialBuckets() to disable.

        IndexWriterConfig config = new IndexWriterConfig(analyzer);
        config.setMergePolicy(policy);
          }
        }
        """;
    JavaFileObject unit =
        new SimpleJavaFileObject(URI.create("string:///Example.java"), JavaFileObject.Kind.SOURCE) {
          @Override
          public CharSequence getCharContent(boolean ignoreEncodingErrors) {
            return source;
          }
        };
    DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<>();
    List<String> options =
        List.of(
            "-classpath", System.getProperty("java.class.path"),
            "-d", createTempDir().toString(),
            "-proc:none");
    boolean compiled =
        ToolProvider.getSystemJavaCompiler()
            .getTask(null, null, diagnostics, options, null, List.of(unit))
            .call();
    assertTrue(diagnostics.getDiagnostics().toString(), compiled);
  }
}

Command

# $LUCENE: a built checkout (./gradlew jar); $REPRO: the directory holding org/apache/lucene/index/Test...java
# $DEPS: junit 4.13.2, randomizedtesting-runner 2.9.2, hamcrest 3.0
V=11.0.0-SNAPSHOT
CP=$LUCENE/lucene/core/build/libs/lucene-core-$V.jar:$LUCENE/lucene/codecs/build/libs/lucene-codecs-$V.jar:$LUCENE/lucene/test-framework/build/libs/lucene-test-framework-$V.jar:$DEPS
javac -d out -cp "$CP" $REPRO/org/apache/lucene/index/TestTemporalMergePolicyJavadocExample.java
java -ea -Dtests.seed=DEADBEEF -cp "out:$CP" org.junit.runner.JUnitCore org.apache.lucene.index.TestTemporalMergePolicyJavadocExample
# assertions off, same result: java -da -Dtests.asserts=false ...

Expected: The copied example compiles.
Observed: One javac error, cannot find symbol: method setBaseTimeSeconds(int), location: class TemporalMergePolicy, with assertions on and off, on main and on the 10.6.0 jars.

All files of this repro: repro/LFV-1020/

More files, environment, full output191 words

The block in the test was checked mechanically against TemporalMergePolicy.java:59-68 at 645d4fe14a20: it is verbatim.

/Example.java:8 in the output is line 8 of the compiled snippet, which is line 61 of TemporalMergePolicy.java.

No separate regression test is suggested: this test copies the example, so it would not notice a later edit of the javadoc, and Lucene has no harness that compiles javadoc examples (LUCENE-8488, #9534). Lucene's testMergesWorkWithUncommittedSegments already calls the real setter in a chain (with other values).

Environment

lucene	`main 645d4fe14a20 (11.0.0-SNAPSHOT); the 10.6.0 release jars give the same error`
jdk	`OpenJDK 25.0.3 (build 25.0.3+9-LTS)`
os	`Linux aarch64 (a compile-only check; the platform cannot change the result)`

Observed output

# the command above, main 645d4fe14a20, seed DEADBEEF, -ea (-da identical); lines in order, banner left out, ... = remaining runner frames
There was 1 failure:
1) testClassJavadocExampleCompiles(org.apache.lucene.index.TestTemporalMergePolicyJavadocExample)
java.lang.AssertionError: [/Example.java:8: error: cannot find symbol
    .setBaseTimeSeconds(3600)                // Base window size: 1 hour
    ^
  symbol:   method setBaseTimeSeconds(int)
  location: class org.apache.lucene.index.TemporalMergePolicy]
	at __randomizedtesting.SeedInfo.seed([DEADBEEF:9A7EBD6A0F12FB11]:0)
	at org.junit.Assert.fail(Assert.java:89)
	at org.junit.Assert.assertTrue(Assert.java:42)
	at org.apache.lucene.index.TestTemporalMergePolicyJavadocExample.testClassJavadocExampleCompiles(TestTemporalMergePolicyJavadocExample.java:68)
	...
FAILURES!!!
Tests run: 1,  Failures: 1

# the same test on the 10.6.0 release jars, -da: tests_run=1 failures=1, the same single diagnostic

Why it looks unintended

The block is headed "Configuration:", nothing marks it as pseudo-code, and every other call in it exists with exactly those types.
The PR history shows a missed update: the same day the setter was renamed, a review commit edited the example three lines below and left this line alone.
Lucene's own test uses setBaseTimeInSeconds(3600), in a chain with other values.

The full argument208 words

Offered as working code. The example is the class's only configuration recipe, under "Configuration:", with no pseudo-code marker.
History of PR #15620. In the first PR commit (bd45e5dbce8e, 2026-01-26) the setter was setBaseTimeSeconds(long) and the example matched. 3560f73a24a6 (2026-02-11) applied a reviewer's suggestion (shubhamsrkdev, review comment r2791054529) to rename it setBaseTimeInSeconds. b4bc4b7ff4b4 "Changes per PR review", the same day, replaced .setUseExponentialBuckets(true) in the example with the comment about disableExponentialBuckets() and renamed the @see tag to #setBaseTimeInSeconds; its diff hunk starts at line 61 and shows .setBaseTimeSeconds(3600) as unchanged context. The review's other API change reached the example; the setter rename did not.
No record accepts the old name. No CHANGES or MIGRATE text, review comment, issue or list thread mentions it; none of the 38 comments on #15620 mentions the example.
Precedent: a stale example fixed as an ordinary doc fix. Issue #12666 (the "Simple example" in the Analyzer class javadoc overrides normalize() without its String fieldName parameter) was closed by PR #12693, "chore: update the Javadoc example in Analyzer", merged by msokolov on 2023-10-18 (commit 6fde1db2281, one javadoc line). Similar outside reports for other classes are open now (issue #16922, PRs #16904 and #16949); LUCENE-8488 (#9534) asks for compile-checked examples in general.

The devil's-advocate check153 words

Strongest case for "noise, not a bug": the block is an illustrative fragment that already uses an undeclared analyzer; the class is @lucene.experimental; 3600 is the default anyway; the error is loud, the right name differs only by "In" and is documented in the same javadoc. A similar javadoc typo (advannceExact in a NumericDocValues example) was set aside as too trivial. The devil's-advocate verifier rated this "moderate" as a triviality argument and "weak" as an intended-behaviour argument.

Why it fails: a reader supplies context such as analyzer, but no context makes a nonexistent method compile. @lucene.experimental allows the API to change; it does not make the shipped example right. The name is API drift from a review rename, not a misspelling, in the only configuration example of a public class shipped in four releases. Every verifier and the adjudication called it real; the adjudication kept it at Low priority.

Suggested fix

Recommended Use the real setter name in the example (validated)

Change line 61 of the example to .setBaseTimeInSeconds(3600) (javadoc only, one line). Validated: the patched example compiles on main and on 10.6.0 and sets the commented values, and the 11 TemporalMergePolicy tests pass.

- *     .setBaseTimeSeconds(3600)                // Base window size: 1 hour
+ *     .setBaseTimeInSeconds(3600)              // Base window size: 1 hour

All options and trade-offs3 options · 260 words

One fix was validated, with the one-line diff applied to 645d4fe14a20; the alternatives were not run.

Use the real setter name in the example (validated) (recommended)

Javadoc only, lucene/core/src/java/org/apache/lucene/index/TemporalMergePolicy.java:61; the trailing comment keeps its column.

- *     .setBaseTimeSeconds(3600)                // Base window size: 1 hour
+ *     .setBaseTimeInSeconds(3600)              // Base window size: 1 hour

Trade-offs

None for users: documentation only, and no CHANGES entry is strictly needed.

What the checks validated

The "Configuration:" block extracted from the patched file (which differs from 645d4fe14a20 only on line 61), compiled by the same one-test check: passes 1 of 1 on main with assertions on and off and on the 10.6.0 jars. The stock block fails the same test, so the test detects the bug.
A separate control test shows that the corrected example sets the commented values: field timestamp, getBaseTimeInSeconds() == 3600, min 4, max 8, ratio 1.2, exponential buckets on.
./gradlew :lucene:core:test --tests "org.apache.lucene.index.TestTemporalMergePolicy*" -Ptests.seed=DEADBEEF: 11 tests (TestTemporalMergePolicy 7, TestTemporalMergePolicyAcrossBuckets 4), 0 failures.
./gradlew :lucene:core:checkGoogleJavaFormat and :lucene:core:renderJavadoc pass, and the rendered class page shows setBaseTimeInSeconds(3600).

Add a `setBaseTimeSeconds` alias (not recommended)

Makes the example compile without editing it.

Trade-offs

Adds API surface to an experimental class only to match a stale doc line; a cross-model reviewer made the same point.

Follow-up: compile-check javadoc examples

The generic wish of LUCENE-8488 (#9534, open since 2018), for example via the javadoc {@snippet} tag backed by compiled code; Lucene main uses no {@snippet} today.

Trade-offs

Would stop this class of drift, but it is a build-infrastructure change, not part of this fix.

How it was found

No formal method. A probe compiled javadoc code examples against the main jars and hit this error; the hunt then extracted the block mechanically, checked in 159 core jars which API members exist, and wrote the one-test repro. Independent verifiers reproduced it with their own tests.

The method in full87 words

First signal. A probe compiled core, search, index and geo javadoc examples against the stock main 645d4fe14a20 jars and got the error on this block (2026-10-29).
Hunt. A hunt unit for javadoc examples re-ran the lead, extracted the block mechanically, and ran a bytecode scan over 159 Lucene core jars (1.9.1 to main) for every API member the example calls, with boundaries cross-checked by javac. The scan shows the class only from 10.5.0 on and no setBaseTimeSeconds anywhere.
Tier. Non-formal: it compiles documentation code and scans jars.

Prior reports, history and checks

Prior reports

No prior report: GitHub issues and PRs (with the migrated JIRA archive), commits, the dev@, java-user@, issues@ and commits@ lists, downstream repositories and the web were searched on 2026-10-29; re-checked 2026-11-01. setBaseTimeSeconds matches no issue, PR or commit anywhere on GitHub; no open or recent PR touches the file.

Searches3 searches

Related, not reports: #15620 added the class (its rename suggestion r2791054529 is about the setter, and no comment mentions the example); #15412 is the feature request; LUCENE-8488 (#9534) is a generic wish to compile examples; #16922 and #16904 fix stale snippets in other classes; #15986 (closed unmerged, wrong base) still carries the stale call.

Others file javadoc fixes almost daily (#16904, #16922, #16949).

What was searched, when, and what turned up
Where	When	How	Found
Scripted searches, 3 runs	2026-10-29	51 queries each (identifiers and error text; feature phrasing; a generic stale-example sweep) over GitHub issues, PRs and commits, downstream repositories, dev@, java-user@, issues@, commits@ and the JIRA archive	only #15620 (the origin) and generic context
GitHub, manual	2026-10-29	`setBaseTimeSeconds` across all of GitHub; all 38 comments of #15620; the changed files of all 415 open PRs, 47 recently updated PRs and 103 PRs closed unmerged since 2026-03-17; the file's history on every live branch	0 hits for the name; no PR touches the file except #15986 (wrong base, not a fix)
Re-check	2026-11-01	issue and PR search for `setBaseTimeSeconds`, `TemporalMergePolicy`, `setBaseTimeInSeconds`; the changed files of all 51 PRs updated since 2026-10-29; issues created since then; line 61 on main, branch_11x and branch_10_6	0, #15620 only, #15620 only; no PR touches the file (incl. #16949, 27 files); line 61 unchanged

History

Stale since the class first shipped: PR #15620 renamed the setter on 2026-02-11 and kept the example; it reached main in the squash commit 1596b7604b67 and shipped in 10.5.0 through the backport 4a2c3fd0901c (both 2026-03-17). 10.4.0 and older have no such class.

Versions tested4 rows

Inside PR #15620: bd45e5dbce8e (2026-01-26) example and setter both setBaseTimeSeconds; 3560f73a24a6 (2026-02-11) setter renamed to setBaseTimeInSeconds on a reviewer's suggestion; b4bc4b7ff4b4 (same day) edited the example three lines below (lines 64-65) and the @see tag, not line 61.
Merged: 1596b7604b67 on main and 4a2c3fd0901c on branch_10x (released in 10.5.0), author date 2026-03-17, GitHub user churromorales. These are the only commits on the file on main and branch_10_6.
branch_10x, where the hunt reproduced it at 657014b3c579, was decommissioned upstream on 2026-10-29 (#16911).
"New in 10.5.0" rests on the release tags (10.4.0 has no such file). On main, lucene/CHANGES.txt lists the entry GITHUB#15620 (line 1385) under the "Lucene 10.4.0" heading (line 1298); a side observation, not claimed.

Versions and branches executed, with results
Version or commit	Verdict	Result
main `645d4fe14a20`; upstream main `f815e679bf6c`	affected	fails with the single error, -ea and -da (upstream main read, not run: line 61 unchanged)
10.6.0	affected	fails with the single error (release jars, -da)
10.5.0, 10.5.1, 10.5.2	affected	fails with the single error
10.4.0 and older, 9.x	no such class	not affected: `TemporalMergePolicy` does not exist there

Independent checks

A finder, an independent reproducer, a reviewer from another model family (OpenAI GPT-5.6) with lenses, a devil's-advocate check, an adjudication and an audit looked at it. All reproduced it; the adjudication confirmed it with high confidence as a Low documentation defect.

Checks and verdicts194 words

The cross-model reviews executed code; they ran on an older checkout where the file is byte-identical to 645d4fe14a20.

Each independent check and its verdict
Check	Verdict	What it found
Finder	reproduced (doc)	Bytecode scan of 159 core jars plus the compile check: fails on main (-ea, -da), 10.6.0 RC1, branch_10x and 10.5.2; the fix check passes.
Refute lens (OpenAI GPT-5.6)	real, high	Reproduced with its own source-extracted test; the patched source passes; the 11 TemporalMergePolicy tests pass with the fix.
Reproducer	real	Own test with only the core jar on javac's class path: fails on main (-ea, -da), 10.5.2 and 10.5.0; the corrected control passes 3 of 3.
Intended lens (OpenAI GPT-5.6)	real, high	Intended argument weak; an alias is not needed.
Devil's advocate	real (Low doc defect)	Re-ran on main (-ea, -da) and 10.5.0; the PR history shows a missed update.
Adjudication and audit	confirmed (high), Low	Re-ran on main (-ea and -da); the one-test repro fails and its fixed twin passes.
Brief	verified; fix validated	Minimal test fails on main (-ea, -da) and on 10.6.0; the patched block passes; the module's TemporalMergePolicy tests pass.

Diagram file

The diagram as a still image, generated with AI and checked against the code. It is under 10 MB, the limit for a GitHub attachment.

PNG 391 KB

Sources and provenance

Finding record, Lucene and upstream sources, repro files and diagram notes1,304 words

Finding record

LFV-1020, snapshot of 2026-11-06

Registry title: TemporalMergePolicy's class javadoc 'Configuration:' example calls .setBaseTimeSeconds(3600), a method that does not exist: the setter was renamed to setBaseTimeInSeconds(long) during review of #15620 and the example kept the old name, so it has not compiled on any release (documentation defect)
Area: core / index merge policy (TemporalMergePolicy class javadoc example)
Priority: Low, rank 1251: The only configuration example of the opt-in experimental TemporalMergePolicy (new in 10.5) fails loudly at compile time on a one-token rename, and people adopting the new feature are likely to copy it.
Impact class: minor
Impact note: Documentation only, with no runtime effect: a developer who adopts TemporalMergePolicy (an opt-in, @lucene.experimental merge policy, new in 10.5.0) and copies the only configuration example in its class javadoc gets one compile error, 'cannot find symbol: method setBaseTimeSeconds(int)', on every release that has the class, and has to find setBaseTimeInSeconds further down the same javadoc; no configuration, scale or special input is involved.
Summary: The TemporalMergePolicy class javadoc shows, under 'Configuration:', how to build the policy with a fluent chain: setTemporalField("timestamp"), setBaseTimeSeconds(3600), setMinThreshold(4), setMaxThreshold(8) and setCompactionRatio(1.2), then passes it to IndexWriterConfig.setMergePolicy. The class has no setBaseTimeSeconds method: its setter is setBaseTimeInSeconds(long), renamed on a reviewer's suggestion while #15620 was in review, so the copied example fails with javac 'cannot find symbol: method setBaseTimeSeconds(int)'. With setBaseTimeInSeconds(3600) the example compiles and the getters return exactly the commented values, so only the javadoc is wrong.
Introduced: 1596b7604b67 (main) and its branch_10x backport 4a2c3fd0901c (the one released in 10.5.0): the squash commits of PR #15620 'Add Temporal Merge Policy for time-series data' (opened by GitHub user churromorales; author date 2026-03-17), which added the class with the example already stale. Inside the PR the example matched the code in the first commit bd45e5dbce8e (2026-01-26: example and setter both setBaseTimeSeconds); 3560f73a24a6 (2026-02-11) applied a reviewer's suggestion (shubhamsrkdev, discussion_r2791054529) to rename the setter to setBaseTimeInSeconds(long), and b4bc4b7ff4b4 ('Changes per PR review', same day) edited the same example block (the exponential-buckets line), the @see tag and the tests, but left line 61 unchanged. These are the only commits on the file on main, branch_10x and branch_10_6 [read: PR commit history and per-commit file text through the GitHub API; local git log -S setBaseTimeSeconds --all finds only 1596b7604b6 and 4a2c3fd0901] (2026-03-17 (1596b7604b67 and 4a2c3fd0901c, author date); inside the PR the example became stale on 2026-02-11 (3560f73a24a6, author date))
First affected version: 10.5.0 [exec] (the first release with TemporalMergePolicy; 10.4.0 and 9.12.3 do not have the class [exec])
Affected versions: 10.5.0, 10.5.1, 10.5.2, 10.6.0 (RC1 4ae946e5a9b), branch_10x 657014b3c579 and main 645d4fe14a20; not fixed upstream (upstream main HEAD still 645d4fe14a20 at 2026-10-29, and line 61 still reads '.setBaseTimeSeconds(3600)' there). [exec: 10.5.0, 10.5.1, 10.5.2, the 10.6.0 RC1 (finder's test and a core-jar-only probe), branch_10x 657014b3c579 and main (-ea and -da) each fail with the single error at TemporalMergePolicy.java:61; the corrected example compiles on 10.5.0, the 10.6.0 RC1 and main] [read: a bytecode scan of 159 core jars finds the class only from 10.5.0 on and no setBaseTimeSeconds of any arity in any of them; the release tags 10.5.0, 10.5.1, 10.5.2 and 10.6.0 are the only tags containing 4a2c3fd0901c]. Not affected: 10.4.0 and older and all 9.x, which have no TemporalMergePolicy (the repro fails there only with 'cannot find symbol: class TemporalMergePolicy'). Not new in 10.6: 10.5.0 to 10.5.2 already have it. Caveat: all runs used JDK 25 on Linux aarch64.
Status: documented (brief, checks and a per-finding doc exist)
Verification: Confirmed by AI-run checks: an independent repro, a cross-model review that agreed, an intended-behaviour check, a prior-report search and a skeptical audit; not yet triaged by a person.
Found by: non-formal
Upstream and prior reports: none found (searched 2026-10-29; the finder's, the independent reproduction's and the intended-behaviour check's searches and the adjudication's recheck agree): scripted searches in three runs (identifier and error-text queries, feature and doc phrasing, a generic stale-example sweep; each 16 GitHub issue and PR queries, 3 commit queries, 2 downstream-repository queries, 20 mailing-list queries over dev@, java-user@, issues@ and commits@, 4 JIRA-archive queries), manual GitHub searches (apache/lucene and all of GitHub for setBaseTimeSeconds: 0 issues, PRs or commits; three downstream search-engine repositories: 0), all 21 review line comments and 17 conversation comments of #15620, the changed files of all 415 open apache/lucene PRs (finder), of the 47 PRs updated since 2026-10-27 and of the 103 PRs closed unmerged since 2026-03-17, the commits on the file on main, branch_11x, branch_10x, branch_10_6 and branch_10_5, and web searches. Read but not the same bug: #15620 (the PR that added the class; the reviewer's rename suggestion discussion_r2791054529 is about the setter, and no comment mentions the example), #15412 ('Date Tiered Compaction', the feature request), the dev@ thread 'PR review: TemporalMergePolicy' (2026-03-13, a review request), #9534 (LUCENE-8488, open: a generic wish to compile-check javadoc examples, from 2018, naming no class), #14257 and #15225 (generic snippet and javadoc-quality threads), #16922 and #16904 (outside javadoc-snippet reports for other classes), #15986 (a wrong-base PR whose copy of the file still has the stale call). Recheck: upstream main HEAD still 645d4fe14a20, the only commit on the file on main, branch_10x and branch_10_6 is the #15620 one, line 61 unchanged, GitHub search for setBaseTimeSeconds 0 hits (apache/lucene and all of GitHub), TemporalMergePolicy items updated since 2026-10-28: 0, no apache/lucene issue or PR updated since a recent cutoff. Tracking issue #16937 does not name it.
Lucene commit tested: main 645d4fe14a20 (2026-10-28): the minimal test fails with assertions on and off (standalone, with a plain javac/java command); the 10.6.0 release jars give the same single error; 10.5.0 to 10.5.2 were run in the version-history runs; the fix was checked with the one-line diff applied to 645d4fe14a20 (the patched example compiles on main and on 10.6.0; the 11 TemporalMergePolicy tests pass; ./gradlew :lucene:core:checkGoogleJavaFormat and :lucene:core:renderJavadoc pass, and the rendered class page shows setBaseTimeInSeconds(3600)). Upstream main f815e679bf6c (2026-11-01) was read, not run: line 61 is unchanged.

Lucene and upstream sources

Finding record: lucene/core/src/java/org/apache/lucene/index/TemporalMergePolicy.java lines 56-68 (the 'Configuration:' example; '.setBaseTimeSeconds(3600)' at line 61), line 94 (@lucene.experimental), lines 146-172 (setBaseTimeInSeconds(long), 'Default is 3600 seconds (1 hour)', getBaseTimeInSeconds() with '@see #setBaseTimeInSeconds')
lucene/CHANGES.txt line 1385 ('GITHUB#15620: Add Temporal Merge Policy for time-series data', under the 'Lucene 10.4.0' header at line 1298; side observation only, see notes)
The finding in 30 seconds: a Lucene main checkout (645d4fe14a20) lucene/core/src/java/org/apache/lucene/index/TemporalMergePolicy.java:56-68 (the "Configuration:" example; line 61), :94 (@lucene.experimental), :102, :128, :145-174 (setBaseTimeInSeconds, getBaseTimeInSeconds, @see), :161, :187, :220, :245, :281
a Lucene main checkout (645d4fe14a20) lucene/core/src/test/org/apache/lucene/index/TestTemporalMergePolicy.java:263-272 (testMergesWorkWithUncommittedSegments: setTemporalField("timestamp_tl"), setBaseTimeInSeconds(3600), setMinThreshold(3), setMaxThreshold(4), setCompactionRatio(1.0))
a Lucene main checkout (645d4fe14a20): grep for setBaseTimeSeconds over lucene/ (only TemporalMergePolicy.java:61); a Lucene clone: git grep setBaseTimeSeconds at releases/lucene/10.5.0, 10.5.1, 10.5.2, 10.6.0 (only TemporalMergePolicy.java:61 in each)
Why it looks unintended: a Lucene main checkout (645d4fe14a20) lucene/core/src/java/org/apache/lucene/index/TemporalMergePolicy.java:56-68
GitHub API (read-only, 2026-11-01): commit b4bc4b7ff4b4 patch of TemporalMergePolicy.java (hunk @@ -61,18 +61,18 @@ with .setBaseTimeSeconds(3600) as context)
a Lucene main checkout (645d4fe14a20) lucene/core/src/test/org/apache/lucene/index/TestTemporalMergePolicy.java:266-272 (its own chain: "timestamp_tl", 3600, 3, 4, 1.0)
Suggested fix: a Lucene main checkout (645d4fe14a20): grep for {@snippet} over lucene/ (0 hits)
GitHub API (read-only, 2026-11-01): changed files of PR #16949 include lucene/core/src/java/org/apache/lucene/index/UpgradeIndexMergePolicy.java, hunk @@ -62,7 +62,7 @@ (shouldUpgradeSegment javadoc); LFV-1021's example is UpgradeIndexMergePolicy.java:37 at 645d4fe14a20
History: a Lucene main checkout (645d4fe14a20) lucene/CHANGES.txt:1298 ("Lucene 10.4.0" heading), :1385 (GITHUB#15620 entry)
a Lucene clone: releases/lucene/10.4.0 (no TemporalMergePolicy.java), releases/lucene/10.6.0 (tag commit 4ae946e5a9b9); git tag --contains 4a2c3fd0901c (10.5.0, 10.5.1, 10.5.2, 10.6.0)

Other statements trace to the hunt's working files (models, logs, reviews and briefs), which are not published.

Repro files

TestTemporalMergePolicyJavadocExample.java (one test, public API): repro/LFV-1020/TestTemporalMergePolicyJavadocExample.java (70 lines)

About the diagrams

Made in parallel with this doc from the mechanism in the brief; the PNG is the summary frame.

assets/LFV-1020/bug.png (391 KB)

Built 2026-11-06 from the hunt's record of this finding and its doc file. Lucene main under test in this hunt: ea57360912ed. Every listed finding was re-run on Lucene main e1faeba08bde on 2026-11-02.

The finding in 30 seconds

Who is affected

The example (main 645d4fe14a20)

The real setter

Why nothing caught it

Not claimed

Minimal repro

Environment

Observed output

Why it looks unintended

Suggested fix

Use the real setter name in the example (validated) (recommended)

Add a setBaseTimeSeconds alias (not recommended)

Follow-up: compile-check javadoc examples

How it was found

Prior reports, history and checks

Prior reports

History

Independent checks

Diagram file

Sources and provenance

Finding record

Lucene and upstream sources

Repro files

About the diagrams

The example (main `645d4fe14a20`)

Add a `setBaseTimeSeconds` alias (not recommended)