Task: Describe the engine setting parameters
Table of Contents
This page documents a task in the See and change everything a report runs story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
Extend the parameter definition with a label, a help line, a full description, a default, a format, the release that introduced the parameter and the release that removed it. Seed the 15 Setup parameters of the engine settings with the text of the prototype, and link each engine settings column to its definition, so the screens, the importer and the checks read one source.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | See and change everything a report runs |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-22 |
3. Acceptance
- The parameter definition holds label, help, description, default, format, introduced_in and removed_in, and the model, the generated SQL and the C++ carry them.
- The 15 engine settings are rows of the definition in the Setup scope, each with the full description, default, format and release range of the prototype.
- Each engine settings column names its parameter definition, and a test fails when a column has none.
- The analytic parameters keep working while the new fields are empty. The analytics task later filled the fields and made them required.
4. Plan
- Add seven nullable columns to the model
ores.reporting.parameter_definition:label,help,description,default_text,format,introduced_inandremoved_in. Regenerate the SQL, C++ and TypeScript. A nullremoved_inmeans the parameter still exists. - Keep the 15 texts in one Python module in
projects/ores.sql/utility, asfile_type_descriptions.pydoes for the file types. The words come from the prototypesee-the-engine-settings-a-party-holds. A generator writesreporting_setup_parameter_definitions_populate.sqland has a--checkmode. The existing seed has no generator and covers only analytic parameters, so the new script owns the Setup scope only. - The link between a column and its definition is the name. The column
n_threadsmatches the Setup parameternThreads. A pgTAP test fails when a value column of an engine settings part has no definition, or when a definition has no column. - The importer keeps its
engine_bindingtable. Reading it from the definitions is a later change. - Keep the prototype and the seed in step: a check compares the texts of both.
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
| Setup parameters seeded with full text | 15 | python3 projects/ores.sql/utility/generate_setup_parameter_definitions_populate.py --check |
see PR |
| pgTAP checks on the definitions | 4 of 4 pass | ./compass.sh sql -- -f projects/ores.sql/test/reporting_setup_parameter_definitions_test.sql |
see PR |
| Shell reporting tests | 1052 assertions in 380 test cases pass | ores.shell.reporting.tests |
see PR |
| Reporting core tests | pass | ./compass.sh test run -- -R ores.reporting.core.tests |
see PR |
6. Notes
- The link between an engine settings column and its definition is the name. The column
n_threadsis the Setup parameternThreads. A pgTAP test checks both directions. A foreign key would need a column on each part table for no gain. - The texts are those of the prototype
see-the-engine-settings-a-party-holds. Most describe the effect and when to change the setting. Onlylog_maskandobservation_modelgive worked values. The owner may ask for examples on the others. introduced_inholds the text a screen shows, for example1.8.0.7 or earlier, so a bound the project could not measure stays visible.- The seed of the analytic parameters had no generator. The task that documents the analytic parameters added one.
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
10. Result
The parameter definition gained the fields a screen shows: label, help, description, default, format, introduced_in and removed_in. The 15 Setup parameters of the engine settings are seeded with the full text of the prototype by generate_setup_parameter_definitions_populate.py, and a pgTAP test ties each setting column to its definition by name.
The entity was renamed to ore_parameter by the next task, and the generator and test names follow it. This task ships in the PR of that task, because the branches are stacked.