check-env-doc is red on main a THIRD time today: VT_QWEN35_STAGE_RESERVE_BYTES from #2349, and the recurrence is the finding
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 423
- Forks
- 53
- Avg merge
- 20h 26m
- Merged PRs (30d)
- 310
Description
check-env-doc is red on origin/main again — the third time today, from the same row, in the
same shape. Every branch cut after #2349 inherits a failing preflight and cannot reach a green gate
before push.
VT_QWEN35_STAGE_RESERVE_BYTES on origin/main at 85f65b0e8:
| surface | occurrences |
|---|---|
src/ + include/ |
1 |
docs/ENVIRONMENT.md |
0 |
scripts/env-doc-allowlist.txt |
0 |
python3 scripts/check-env-doc.py on a clean extract of origin/main exits 1 naming that variable.
The pattern is now the finding
| # | knob | row | fixed by |
|---|---|---|---|
| #2312 | VT_DFLASH_BOUNDS_DEVICE |
(#2304) | #2313, in flow |
| #2329 | VT_QWEN35_STAGE_MIN_FREE_FRAC |
PERF-QWEN35-STAGE-WEIGHTS (#2328) |
#2332 |
| this | VT_QWEN35_STAGE_RESERVE_BYTES |
PERF-QWEN35-STAGE-WEIGHTS (#2349) |
— |
Three in one day, two from the same row and the same knob family. The previous two were each treated
as an oversight and fixed with a doc entry. At three, the oversight explanation stops being the
useful one.
The mechanism is structural, and it is visible in the checker's own position. check-env-doc
compares src/+include/ against the doc surfaces. It can only run against a tree that already
contains the knob — so it cannot fail on the branch that introduces one unless that branch happens
to run preflight after adding it and before pushing. It therefore fires for the first time on
main, where it is nobody's branch, and lands as a base failure every later branch inherits. The
gate is correct; its position means the cost falls on everyone except the author.
What would actually close it
A doc entry for VT_QWEN35_STAGE_RESERVE_BYTES fixes today. It will not stop the fourth. Options
for whoever owns the checker, roughly in order of cost:
- Have
check-env-docalso run in the PR-scoped diff gate, so a branch adding a knob reds on that
branch rather than onmain. - Require the doc entry at the point of introduction — a check that a newly added
VT_*read in
src/has a matching doc or allowlist line in the same commit. - Accept the recurrence and treat it as routine base maintenance, which is what is happening now by
default rather than by decision.
This issue is not asking for a design; it is recording that the same failure has now happened three
times in a day and that the third one is again blocking open branches.
Owner: PERF-QWEN35-STAGE-WEIGHTS for the knob, and whoever owns check-env-doc for the position
question. Found while landing W5e-2 under #2336; not fixed there, because bundling another row's
knob into a model-port branch is what #2329 already declined to do.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing python3 scripts/check-env-doc.py on the cited origin/main revision, then read scripts/check-env-doc.py and the CI or preflight configuration that invokes it. Compare the src/ and include/ occurrence with docs/ENVIRONMENT.md and scripts/env-doc-allowlist.txt, and review the listed PR-scoped and same-commit options. Done requires an agreed mechanism that prevents newly introduced environment knobs from first failing on main.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, python
- Domain
- build-system, ci-cd, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100