spuru9 opened a new pull request, #28842:
URL: https://github.com/apache/flink/pull/28842
## What is the purpose of the change
`ConfigurationOptionLocator` discovers `ConfigOption`s from a hard-coded
list of packages and reads each one with `Files.newDirectoryStream`, which does
not recurse into sub-packages. An option class in a sub-package of a searched
package is therefore dropped from the generated configuration reference without
any error, and `ConfigOptionsDocsCompletenessITCase` cannot detect it because
it derives its expectations from the same list.
All seven `state.backend.rocksdb.manual-compaction.*` options are affected.
Each one carries
`@Documentation.Section(Documentation.Sections.EXPERT_ROCKSDB)`, an explicit
statement that it belongs in the reference, but the class lives in
`org.apache.flink.state.rocksdb.sstmerge` while only the parent package
`org.apache.flink.state.rocksdb` is searched. As a result the manual compaction
feature added in 1.20 has no documented configuration: six of the seven keys
appear nowhere under `docs/`, and the seventh appears only in the 1.20 release
notes.
## Brief change log
- Added an `OptionsClassLocation` for
`org.apache.flink.state.rocksdb.sstmerge` and regenerated the affected tables:
`expert_rocksdb_section.html` grows from 4 to 11 rows, and
`rocksdb_manual_compaction_configuration.html` is new. No other generated table
changes.
- Annotated `RocksDBManualCompactionOptions` with `@PublicEvolving`.
Becoming discoverable also subjects the class to
`ConfigOptionsDocGenerator#verifyClassAnnotation`, which fails the docs build
unless the class declares a stability level, so the location entry alone would
turn a silent gap into a build failure. `@PublicEvolving` matches
`RocksDBOptions` and `RocksDBConfigurableOptions` in the same module.
- Fixed two option descriptions that were missing a space between
concatenated sentences, rendering as "to start.If" and "to start.Note".
Harmless while the options were invisible, user-visible now.
- Added `ConfigurationOptionLocatorTest`, which scans the source tree and
fails when a `@Documentation.Section` option sits in a package the locator does
not search.
The scan is deliberately left non-recursive. Around 30 connector and format
option classes sit outside `LOCATIONS` on purpose because they are documented
by hand on their own pages, and making discovery recursive would pull all of
them into the configuration reference.
## Verifying this change
This change added tests and can be verified as follows:
- `ConfigurationOptionLocatorTest` fails when the new `LOCATIONS` entry is
removed and passes with it. Both directions were verified locally. This is the
check that matters, because `ConfigOptionsDocsCompletenessITCase` is green in
both states, which is precisely why the gap went unnoticed.
- Repo-wide the new test reports exactly one violation before the fix and
none after, so it needs no exclusion list.
- `mvn -pl flink-docs verify` passes: 21 unit tests and 3 ITCases, including
`ConfigOptionsDocsCompletenessITCase`.
- Regenerating with `-Dgenerate-config-docs` produces only the two rocksdb
files listed above.
## Does this pull request potentially affect one of the following parts:
- Dependencies (does it add or upgrade a dependency): no
- The public API, i.e., is any changed class annotated with
`@Public(Evolving)`: yes. `RocksDBManualCompactionOptions` gains
`@PublicEvolving`, as required by the docs generator. No option key, default
value or type changes; two descriptions gain a missing space. japicmp excludes
`@PublicEvolving` outside the release process.
- The serializers: no
- The runtime per-record code paths (performance sensitive): no
- Anything that affects deployment or recovery: JobManager (and its
components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
- The S3 file system connector: no
## Documentation
- Does this pull request introduce a new feature? no
- If yes, how is the feature documented? not applicable. The change
documents existing options that were missing from the configuration reference.
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes (please specify the tool below)
Generated-by: Claude Code (claude-opus-5)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
