Promotion: updating the baseline
Promotion: updating the baseline
rqm baseline update is the only thing that writes the baseline. It turns the evidence of one run into records, and it removes records that the evidence no longer supports. Nothing else changes the file: not rqm test, not a requirement, not a hand edit that survives a check.
The rule
A record is written for a requirement only when all of this holds: the requirement is gated now (it has the test method and is approved or required), the run evaluated it as satisfied, the run found it eligible, and the project still is the project the run was made on. Nothing else ever creates or refreshes a record. A run that failed, was incomplete, was stale, was ambiguous, or could not be attributed to the requirement leaves no record.
What is checked first
- The project loads without errors.
- The baseline file is the one the run saw: the same path, and the same bytes (by hash). If it changed since the run, the command stops with
E-BASELINE-CHANGED. A missing file needs--create, and only when it was missing for the run too. - The inputs of the run are compared with the inputs of the project now. A difference the evidence depends on refuses the promotion:
E-SNAPSHOT-CHANGEDfor a requirement, a selector, an annotation or a suite, andE-POLICY-CHANGEDfor the policy. A difference the evidence does not depend on, such as an edit to a source file with no annotation of an evaluated requirement, only warns withW-SNAPSHOT-UNRELATED-CHANGE. - The hash algorithm of the baseline is the one this rqm uses (
E-BASELINE-STALE-ALGOotherwise).
Nothing is written when any of these fails.
What the plan does
For each requirement the plan gives one of these:
| Outcome | When |
|---|---|
promoted |
Satisfied and eligible. The record is written or refreshed. |
retracted |
The record exists and the run says unsatisfied or unknown, or the run was full and the evidence is incomplete, or the record was made under another policy and is not refreshed. |
untouched |
The record exists and this run cannot speak for it: the run was partial, or did not evaluate the requirement. |
orphaned |
The record belongs to a requirement that is not in the project or is no longer gated. It stays unless --prune is given. |
A run is full when every suite of the configuration was selected and clean. A partial run never removes a record because evidence is incomplete, since it did not look at all the evidence. A failure always removes the record.
What a record holds
The effective hash the run evaluated, the run, verified_at (when that run finished, not when it was promoted), the suites that hold the credited cases, how many cases counted and how many of them passed only after a retry, and the provenance: selectors, the tests the cases run, the fingerprint of the mapping, the fingerprint of the part of the policy the requirement depends on, and the version of every adapter that read a report of the run. The update section names the run and the moment of the promotion. The runs section keeps the runs that records refer to, and the run of this update.
How the file is written
The next baseline is built in memory, written to text, read back with the strict reader, and compared with what was built. Only then is a temporary file written next to the target and renamed over it. A failure at any step, including a crash, leaves the old file as it was, or no file when one was being created. When the plan changes nothing, the file is not rewritten.
The command
rqm baseline update [--run <id>] [--create] [--prune]. --run selects a run other than the latest. --create allows the first baseline to be made. --prune drops the records of orphans. Success is exit 0, even when records were retracted: the file was updated as the evidence allows. Exit 2 is a refusal, exit 3 is an internal failure.