Repository navigation
chore(ci): check environment-variables.md against src - #2486
Merged
inureyes merged 2 commits intoOct 20, 2026
Merged
Conversation
docs/environment-variables.md had drifted from the variables the code reads: 110 MLXCEL_* names that appear as string literals under src/**/*.rs were absent from the page. Most of them are test fixtures, probe knobs and build-internal names that should stay off an operator reference, but 22 are read at run time by production code (or are contributor-facing gates of the kind the page already lists) and had no row. Document each in the section that fits, from the code that reads it: values and parse semantics, default, effect, and the component that reads it. Speculative decoding gains the batched-MTP ragged window, the lablup#203 escape hatch, drafter quantization and the lablup#1204 tree-drafting knobs; the OpenXLA section gains the server context buckets, load timing and the Phi-4-multimodal audio precision; the diagnostic sections gain the DSA and MiniMax-M3 dense fallbacks, the CUDA qmm_naive tile pin (with its paired MLXCEL_TRACE_QMM_TILE, read only from CUDA source), the shapeless-compile audit, MTP gap logging, the audio probe dump, the VoiceChat profile outputs, bench phase marks and the MLXCEL_API_KEY log redaction. Kimi K3's per-request media-token budget, MLXCEL_GIT_COMMIT (build time) and MLXCEL_REQUIRE_MODELS (tests and CI) complete the set. The remaining 88 names are allowlisted with reasons by the check added in the next commit.
Nothing kept docs/environment-variables.md in sync with the MLXCEL_* variables the code reads, so every new call site was a silent chance for drift, found only when someone happened to look. scripts/ci/check_env_var_docs.py (standard library only, no toolchain) collects every MLXCEL_* string literal in src/**/*.rs and fails, naming the variable and up to three files that contain it, when a name is neither mentioned on the page nor in the script's ALLOWLIST. The failure message states both resolutions: document the variable, or allowlist it with a reason. It also fails when an allowlist entry is no longer in src or is also on the page, so the allowlist cannot rot, and when the scan finds nothing. The allowlist, not a path or #[cfg(test)] exclusion, carries the exceptions (88 entries, grouped by reason: test-only, fixture-authoring, build-internal, internal diagnostic). MLXCEL_FREEZE_GOLDENS is read from #[cfg(test)] code in a file with no test marker in its name, and several *_tests.rs modules are also compiled into diagnostic builds, so a blanket exclusion would hide names without recording that anyone judged them. tests/test_check_env_var_docs.py covers the checker on synthetic trees: a new undocumented call site, a deleted row for a name still read, stale and contradictory allowlist entries, and an empty scan must each fail. Wire it in like kernel-dtype-keys: `make verify-env-var-docs`, a prerequisite of `make verify` and `make verify-rocm`, and an `env-var-docs` CI job that is not behind the `changes` filter, because a docs-only change that deletes a row has to be gated as well as a src change. CONTRIBUTING.md and the page itself name the new gate. Closes lablup#1140
inureyes
added
status:review
Member
PR Implementation Hardening Summary
|
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.
Summary
Adds a toolchain-free gate that keeps
docs/environment-variables.mdin sync with theMLXCEL_*names read undersrc/, and documents the operator-facing variables that were missing somainpasses it. EveryMLXCEL_*string literal insrc/**/*.rsmust now be on the page or carry a reasoned entry in the checker's allowlist.Related issues
Closes #1140
Type of change
chore— build, CI, dependencies, release infrastructuredocs— documentation onlyTest plan
python3 scripts/ci/check_env_var_docs.py: OK (294 names: 206 documented, 88 allowlisted)python3 -m unittest tests/test_check_env_var_docs.py: 15 tests OKmake verify-env-var-docs: OK; fulltests/Python suite: 139 OK, 28 skippedstd::env::var("MLXCEL_NEW_THING")fails and names itspath:line; deleting theMLXCEL_KIMI_K3_MAX_MEDIA_TOKENSrow fails (both reverted)actionlint .github/workflows/ci.yml: no findings in the new job (the 8 shellcheck infos are pre-existing onmain)insert_apache_header.py --check,git diff --checkNotes for reviewers
d5abf1fa): 294 names insrc, 213 on the page, 110 missing. Of those, 22 operator-facing variables are now documented (speculative decoding, OpenXLA, kernel diagnostics, logging/profiling, media limits, build-timeGIT_COMMIT,REQUIRE_MODELS), each from the code that reads it; 88 are allowlisted by group with a reason (C++ macros frombridge.define,cargo:rustc-envnames, XLA golden-freeze and graph-dump switches, child-process handshakes, sample counts, probe parameters, fixture paths).src/**/*.rs, but 29 are read by C++/CUDA,tests/or scripts and 5 are already marked "Removed in refactor: run mlxcel generate on the engine and retire CxxGenerator #2176", so none were deleted. The optional page-to-src reverse check is not implemented; the script's docstring explains why.make verify-env-var-docsjoinsverifyandverify-rocmand the help list; theenv-var-docsCI job sits besidekernel-dtype-keysoutside thechangesfilter so a docs-only row deletion is also caught. CONTRIBUTING.md now lists tenmake verifyprerequisites and seven cheap gates.src, an entry that is also on the page, or an empty scan.Checklist
docs/.envfiles committed