Repository navigation
docs: T137 — Document the one env_vars table in the reference, the guides and the README - #3683
Conversation
Every layer of minimal.toml and a loadout file sets its variables in one env_vars table, merged by name. The pages say that vars and vars_lenient fail with exit code 3, and give the name rule.
The test parses each toml example in the loadout, minimal.toml and task reference pages, and fails on a vars or vars_lenient key.
|
Important Review skippedBot user detected. Ask an organization administrator to verify that this bot has an active assigned CodeRabbit review seat. See the seat-assignment guide. After the seat is confirmed, request a review again.
|
|
Approved: every review thread resolved at @mitodrummer resolved the last thread, which releases the approval this review had withheld. Nothing to do. |
A sketch with <placeholder> values no longer skips the parse. The test fills each placeholder in and fails on any other toml error.
|
Round 1 of 10 on the runtime's review findings, pushed as
Verify Review threads the coder judged:
A person reading the reference, the guides or the README sets variables in env_vars in minimal.toml and in a loadout file, and learns that vars and vars_lenient fail with exit 3. The check now also fails on any toml example in the reference pages that does not parse after its values are filled in. Notes from the agent: Revise round 1: the line-by-line sketch reader is gone. A sketch now parses after each becomes its bare name and each ', ...' list tail is removed. Then the same table walk as the other examples checks it. cargo clippy -p mfile --all-targets printed no warnings. Commit bodies re-wrapped by the runtime: a prose line over commitlint's 100 is split at a space where no piece is left over it, and code and lines that cannot split are left as written. Every word the coder wrote is kept, in order:
|
|
/arch-review |
1 similar comment
|
/arch-review |
There was a problem hiding this comment.
minimal-review — approved
Verdict APPROVE — every review thread is resolved; @mitodrummer closed the last one. The review of 1c1eb28cb725 withheld this approval on the threads open then. Posted as a comment: the App cannot approve its own pull request; the check and the label carry it.
T137 — Document the one env_vars table in the reference, the guides and the README
slice: S5
kind: enablement
covers: none
size: S
est: 140 code, 60 tests
executor: agent
difficulty: routine
model: light
diagnostics: none: documentation only; the pages name the exit-3 refusal of vars and vars_lenient in words and quote no product text
observability: none: documentation only; nothing runs
layers:
- docs:
- README.md: the loadout example sets [env_vars]
- docs/concepts/loadouts.md: [vars] becomes [env_vars]
- docs/concepts/sessions.md: SHELL is set in [env_vars]
- docs/guide/agents.md: [defaults.session.env_vars]
- docs/guide/dev-shell.md: [defaults.session.env_vars], and a loadout's [env_vars]
- docs/guide/migrate-to-minimal-session.md: profile.env_vars maps to defaults.session.env_vars
- docs/reference/loadouts.md: one [env_vars] section in place of [vars] and [[vars_lenient]], with the name rule and the refusal of the retired keys
- docs/reference/minimal-dot-toml.md: env_vars at every layer, merged by name; the inherit table names env_vars
- docs/reference/tasks.md: env_vars is the task's only variable key, and it merges by name
- check:
- crates/mfile/src/lib.rs: a test that parses each toml example in docs/reference/loadouts.md, minimal-dot-toml.md and tasks.md, and finds no vars or vars_lenient table
test: cargo nextest run -p mfile reference_doc_examples_use_env_vars
produces: none
consumes: none
proof: A person reading the reference, the guides or the README sets variables in env_vars in minimal.toml and in a loadout file, and learns that vars and vars_lenient fail with exit 3.
depends on:
- blocked by #3653
Proof
A person who reads the README, the loadout and session concept pages, the agents, dev-shell and migration guides, or the loadout, minimal.toml and task reference sets variables in env_vars, in minimal.toml at every layer and in a loadout file's [env_vars] table. The minimal.toml reference shows how env_vars merges by name across [defaults], [defaults.], the entry and loadouts. The loadout, minimal.toml and task references say that vars and vars_lenient fail with exit code 3, and give the name rule.
Notes from the agent: The test skips a toml block whose first line is '# user_policy.toml', because the [vars] section of user_policy.toml is a policy section and not a variable layer (tasks.md). A schema sketch with values (the [outputs.] block) is not valid TOML. The test reads its keys line by line, and any other example that does not parse fails the test. I checked that the test fails when a loadout example goes back to [vars]. The [outputs.*] reference now names env_vars for the image variables. The parser still accepts vars there as an alias, and the page no longer mentions that alias. The loadout reference section anchor changed from #vars to #env_vars, and the only link to it (in minimal-dot-toml.md) is updated. The [[vars_lenient]] section is replaced by a 'Retired keys' subsection. I did not run 'just lint-prose' because vale is not installed on this box. 'cargo clippy -p mfile --all-targets' is clean.
Tests
cargo nextest run -p mfile reference_doc_examples_use_env_varsVerify
min task run agent-verifypassed ([tasks.verify]).Closes #3655