Decisions and rejected alternatives

This page lists the choices that shaped rqm, with what was considered and why it was not chosen. It is the place to look before proposing a change that has been proposed before.

Verification and the baseline

Alternative Why it was not chosen
One stored verification value It cannot tell “the last run failed” from “the baseline says verified”. Storing the facts and computing the label can.
Writing verified in the YAML It would be a claim without evidence, and it would drift exactly like the spreadsheet that rqm replaces.
Committing the baseline to the main repository as the default Concurrent pull requests rewrite one file and conflict, and evidence recorded on a contributor’s machine cannot be checked by a reviewer. A baseline written by a controlled CI job cannot be forged from a pull request. Committing it stays possible.
A slimmer or sharded baseline file With a single writer there are no merge conflicts to avoid, so the extra structure buys nothing.
No baseline at all It loses evidence that outlives a run, the release record and the staleness signal. So the baseline is optional: without it, verified means only that the latest run satisfied the requirement.
Built-in baseline backends (git remote, HTTP, S3) Network code, credentials and many failure modes inside a deterministic local tool, and each backend is a permanent cost. rqm reads and writes a path.
Failing rqm test on every state other than verified Every pull request that adds or edits a requirement would fail until it was promoted. pending_baseline and stale are the normal state before promotion.
Promoting inside the pull request as the supported workflow It needs the full test environment on every contributor machine and produces evidence that nobody can check.
Refusing a promotion when the policy changed, unless the run is full Removing the records that the run did not refresh leaves nothing under a policy it was not made under, and needs no extra mode.
Rewriting the baseline when a promotion changes nothing It changes update.run_id and update.at for no new fact, and makes noise in the diff of a file that people merge.
Scoped, per-requirement invalidation It needs per-requirement dependency tracking that cannot yet be shown correct. Invalidation is global and conservative, and the subset fingerprint is already recorded, so the change later is a comparison.
A tamper hash on the run record It detects accidental edits only, and promotion already recomputes the inputs fingerprint.
Exit 1 or exit 3 for a refused promotion Exit 3 means that retrying might help, and a stale run record never becomes promotable without a new run.
Skipping the promotion when the gate of rqm test --promote fails A failing test has to retract the record of its requirement, so the promotion runs after a failed gate too, and the exit code is computed from the final state.
A chain written rqm test --and baseline update, or the option rqm baseline update --test, for running and promoting in one invocation A study of the command-line parser showed that rqm test --promote and rqm baseline update --test both work cleanly, and that a chain of two commands needs extra help pages and extra rules for options. --promote was chosen because rqm test is the command that a person already types. --create and --prune need --promote, and the run to promote cannot be chosen, because it is the one just made.

Binding tests, and what counts as evidence

Alternative Why it was not chosen
Fuzzy or suffix matching of test names A wrong guess silently credits the wrong requirement.
Report properties that grant or override credit An arbitrary requirement id in a report could manufacture credit. Static binding works for any runner. A relaxation can be added later as an explicit opt-in.
A marker that is not an attribute (a doc-comment tag, a cfg_attr, a plain comment) or ids printed at run time A small attribute crate lets the compiler check the marker. Comments are not in the syntax tree, and printed ids link only the tests that ran and depend on how the runner captures output.
A Python source scanner A parser dependency, its own identity grammar and a list of supported forms, for a use that selectors already serve.
A manifest walk or a configured list of targets instead of cargo metadata Cargo knows the targets, the crate names and the binary ids. Anything else copies its rules.
Parsing the nextest binary id to get the crate name The id of a library is the package name, which says nothing about the crate name. The id is a key into the table of targets.
Counting retry attempts as separate cases One flaky test would inflate min_cases. Attempts belong to one logical case.
Informational suites, a minimum case count per requirement and a retry policy Mandatory and optional suites, with the rule that every selector must be matched, cover the need. A flaky case is credited and warned about.
Aliases, suffix matching and targets Each is a second way to name or select the same thing. One id or uuid, one require_suites list and exact selectors cover the need.
Reading the clock to decide whether a report is fresh A file written just after a clock reading was often older than the reading. A reference file written before the suite starts is never newer than the report.

Requirements and identity

Alternative Why it was not chosen
Reciprocal link insertion It rewrites documents that the author did not touch. Links are stored as written.
A generic reference resolver A selector could be resolved as a requirement id. Distinct types make that a compile error.
Lazy inheritance resolution Consumers could see different values for one requirement. Resolution happens once, in the snapshot.
Hashing references as written Every rename would stale every requirement that links to the renamed one. References are hashed as uuids.
serde(flatten), a hand-built event stream or a generic value tree for kind fields Flatten destroys source spans and cannot coexist with strict unknown-field checking. The other two leave the serde approach. A nested fields: map keeps the top level strict.
Partial trust of a file that is partly valid A half-read baseline could show verified from a record it misread. A failed parse contributes nothing.
A published, standardised hash format with a conformance suite Nothing needs a second implementation. The canonical form is internal and pinned by golden digests, and a change to it changes the algorithm id.
Rejecting trailing whitespace in prose Editors leave trailing whitespace all the time, and a rejected file is a poor reward for it. Removing it before hashing is a small, total rule. Its one cost is that the Markdown hard break written as two spaces is lost, and a backslash or <br> replaces it.
A regular expression in rqm.yaml for requirement ids The grammar of an id is fixed (an uppercase prefix, a hyphen and a number), and the project lists the prefixes it uses in id_prefixes. That needs no regular-expression engine, and a prefix is checked once, when the snapshot is built.
Rewriting a whole file to rename a requirement A rename changes the text at the places where the id is written, so comments, the order of fields and everything else stay byte for byte as they were.
Replacing the requirement file after a failed editor When the editor exits with a status other than 0, rqm edit leaves the file untouched. When it exits with 0 and the result is invalid, the file keeps the author’s text and the diagnostics say what to fix.

The tool itself

Alternative Why it was not chosen
Running suites through a shell Word splitting and glob expansion add an injection surface for no benefit.
A parse cache There is no evidence yet that it is needed, and it would be a second thing to validate. The parser sits behind one narrow function, so a cache keyed by content hash can be added later.
Cache keys based on size, modification time or inode, or a metadata-based fingerprint A same-size edit with a preserved modification time would hit a stale entry or be missed. Keys and fingerprints are content hashes.
Treating canonicalization as sufficient path security It leaves a race between the check and the use. rqm opens first, validates the opened object, and documents the risk that remains.
A flag that makes a command faster by skipping checks A flag that trades correctness hides in scripts. There is none.
A byte-exact YAML writer of rqm’s own Nothing may depend on how things are serialized. The requirement is that the file reads back to the same model.
Export, search, shell completion, timings, history and ingesting a report without running the suite None serves the workflow that rqm exists for. The analysis commands have JSON output for anything else.