docs: publish the FULL surface in XFF.md, calling out what a build may lack - #450
Merged
Conversation
…y lack XFF.md was generated with --config=xff_full, which enables only PCRE2, so the archive flags appeared as "NOT built into this binary" instead of being documented. The published reference should describe the TOOL, with a clear callout of what a given build might not include. Two parts, because the config alone was not enough: - --config=xff_docs: every composable extra on, used by xff-md-update.sh AND the CI drift guard so they cannot diverge. Add each new extra here as it lands. - BuildReference(Audience): the per-binary "NOT built into this binary" line is a property of the binary that generated the document, not of the feature, so --markdown now renders Audience::kPublished and omits it. --help / --man keep Audience::kThisBinary, where the note is exactly right: that IS about your build. Necessary because the archive extra has no linkable backend yet, so enabling its flag cannot make the note disappear on its own. The reader is still told what they may not get, by the STATIC text that survives in both audiences: "A build-time extra: the stock binary is lean and omits it (rebuild with --//xff:xff_archive); asking for archive handling without it is a hard error." "A build-time extra: present only in a full build - run `xff --help=extras` to see whether THIS binary has it." XFF.md now carries zero per-binary notes. Three tests pin the split: a published reference has no such note, a this-binary reference does (asserted against the same ExtraEnabled predicate the builder uses, so it holds whichever extras the test binary links), and BOTH audiences still name the rebuild flag.
helly25
enabled auto-merge (squash)
August 10, 2026 23:34
Owner
Author
|
Closing: this was pushed under a new branch name because a rebase had diverged from what was already pushed. Reopening the same work from its original branch (docs/xff-md-all-extras), updated by MERGING main rather than rebasing, so no force-push is needed. |
auto-merge was automatically disabled
August 10, 2026 23:34
Pull request was closed
helly25
enabled auto-merge (squash)
August 10, 2026 23:35
…extras list Two things, both from review of #450. 1. CI caught a missing include that local clang hid transitively: gcc (the default and minimal cells, the latter at -std=c++17) rejected help_build.h:39: error: use of enum 'Audience' without previous declaration because `enum class Audience : std::uint8_t` needs <cstdint>. Added. Worth noting the local build could not have caught this - only the gcc cells compile that path, which is exactly why they exist. 2. "What about other extensions?" - --config=xff_docs listed the extras by hand, and forgetting one is SILENT: no build breaks, the published reference just omits a feature. Now enforced by tools/check_docs_extras.py + the `check-docs-extras` pre-commit hook: every `bool_flag` in xff/BUILD.bazel must be enabled by that config, following --config= inheritance (which matters, since xff_docs gets PCRE2 only by including xff_full). Flags that are not extras go in an allowlist WITH the reason - today only xff_msan, a sanitizer knob rather than a user-facing feature. Verified both directions: it passes on the tree, and deleting the archive line makes it fail naming `--//xff:xff_archive`. 9 unit tests cover direct enabling, inheritance, a bare flag meaning on, an explicit =False, a trailing comment, other configs being ignored, and a config cycle terminating.
helly25
disabled auto-merge
August 11, 2026 00:18
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
XFF.md was generated with
--config=xff_full, which enables only PCRE2 - so the archive flags appeared as "NOT built into this binary" instead of being documented. The published reference should describe the tool, with a clear callout of what a given build might not include.Two parts, because the config alone was not enough:
--config=xff_docs- every composable extra on, used byxff-md-update.shand the CI drift guard so the two cannot diverge. Add each new extra here as it lands.BuildReference(Audience)- the per-binary"NOT built into this binary"line is a property of the binary that generated the document, not of the feature.--markdownnow rendersAudience::kPublishedand omits it;--help/--mankeepAudience::kThisBinary, where the note is exactly right because it IS about your build. This part is necessary because the archive extra has no linkable backend yet, so enabling its flag cannot make the note disappear on its own.The reader is still told what they may not get, by the STATIC text that survives in both audiences:
XFF.md now carries zero per-binary notes.
Three tests pin the split: a published reference has no such note; a this-binary reference does (asserted against the same
ExtraEnabledpredicate the builder uses, so it holds whichever extras the test binary links); and both audiences still name the rebuild flag - that last one is what keeps the callout from being silently lost later.Verified:
bazel test //...green,//xff/cli:xff_markdown_test --config=xff_docsgreen, hooks clean.