rqm rename

rqm rename gives a requirement a new id and changes every reference to it that is written as the old id. The uuid is what the hashes and the baseline use, so a rename keeps them valid.

rqm rename <REQUIREMENT> <NEW-ID>

REQUIREMENT is an id such as RQM-12 or a uuid. NEW-ID is the id the requirement should have.

What changes

  • The id of the requirement itself.
  • Every parent and every links entry that names the old id.
  • Every #[rqm] literal that names the old id in a scanned Rust source.

Everything is changed at the span where the id is written, so comments, the order of fields and the rest of each file are left byte for byte as they were. The requirement keeps its uuid, its file keeps its name, and the effective hash of every requirement stays the same.

What does not change

  • A reference written as a uuid. The uuid is the identity that the hashes and the baseline use.
  • A test selector, because it names a test and not a requirement.
  • The name of the requirement file. rqm finds requirements by their contents, not by their file names.
  • A run record from before the rename. It keeps the id it was written with; the new id appears in the next run.

The baseline stays current, because its records are keyed by uuid and by the effective hash, and neither changes. A required requirement that passed the release gate before the rename passes it afterwards.

Refusals

Nothing is written when the project has an error, when the new id is not an id, when it is the id the requirement already has, or when another requirement has it (E-ID-DUPLICATE). An unknown requirement is E-REQ-NOT-FOUND.

A reference that cannot be changed where it is written, such as "RQM\x2d3", is E-RENAME-IN-PLACE and stops the whole command.

Example

$ rqm rename RQM-2 RQM-20
renamed RQM-2 to RQM-20 in 1 files (1 places)
  requirements/RQM-2.yaml   requirement  1
$ rqm check
checked 4 requirements (loaded 4 of 4 discovered requirement files)

One transaction

rqm reads every affected file once, builds the new bytes in memory, loads and resolves the new requirements, scans the new sources, and checks that every effective hash is the one it had. Only then does it write the files, in path order, through one write plan. A failure at any step puts back every file it had already written, so the repository is byte for byte as it was.

A killed process is not covered: rqm cannot put back a file after it is gone. Each file is replaced atomically, so a reader sees the old file or the new one, never part of either, and the next run can simply be started again.

Options

$ rqm rename --help
Give a requirement a new id and change every reference to it, in one transaction

Usage: rqm rename [OPTIONS] <REQUIREMENT> <NEW-ID>

Arguments:
  <REQUIREMENT>  The id (`RQM-12`) or the uuid of the requirement
  <NEW-ID>       The new id, such as RQM-40

Options:
      --format <FORMAT>  Output format. JSON is the stable contract [default: human] [possible values: human, json]
      --strict           Treat warnings as errors for the exit code. The output itself does not change
  -h, --help             Print help

The data of --format json is described in The JSON output.