Skip to content

docs: publish the FULL surface in XFF.md, calling out what a build may lack - #450

Merged
helly25 merged 7 commits into
mainfrom
docs/xff-md-full-surface
Aug 11, 2026
Merged

docs: publish the FULL surface in XFF.md, calling out what a build may lack#450
helly25 merged 7 commits into
mainfrom
docs/xff-md-full-surface

Conversation

@helly25

@helly25 helly25 commented Aug 10, 2026

Copy link
Copy Markdown
Owner

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 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. --markdown now renders Audience::kPublished and omits it; --help / --man keep Audience::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:

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 - that last one is what keeps the callout from being silently lost later.

Verified: bazel test //... green, //xff/cli:xff_markdown_test --config=xff_docs green, hooks clean.

…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
helly25 enabled auto-merge (squash) August 10, 2026 23:34
@helly25

helly25 commented Aug 10, 2026

Copy link
Copy Markdown
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.

@helly25 helly25 closed this Aug 10, 2026
auto-merge was automatically disabled August 10, 2026 23:34

Pull request was closed

@helly25
helly25 deleted the docs/xff-md-full-surface branch August 10, 2026 23:34
@helly25
helly25 restored the docs/xff-md-full-surface branch August 10, 2026 23:35
@helly25 helly25 reopened this Aug 10, 2026
@helly25
helly25 enabled auto-merge (squash) August 10, 2026 23:35
helly25 and others added 4 commits August 11, 2026 00:40
…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
helly25 enabled auto-merge (squash) August 11, 2026 00:31
@helly25
helly25 merged commit de96ee6 into main Aug 11, 2026
11 checks passed
@helly25
helly25 deleted the docs/xff-md-full-surface branch August 11, 2026 00:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant