rqm edit

rqm edit opens a requirement in your editor, checks the result when the editor exits, and reports any errors found.

rqm edit <REQUIREMENT>

REQUIREMENT is an id such as RQM-12 or a uuid. rqm edits a temporary copy of the requirement file. When the editor exits with status 0 and the copy changed, rqm replaces the requirement file with the edited text through a write plan, then validates the file and reports the diagnostics.

The editor

rqm looks for an editor in the $VISUAL environment variable, then in $EDITOR. The editor is not implemented by rqm: you set it yourself. The value is split on the first space, so that a value such as code --wait works correctly. A quoted path with spaces does not work.

$ VISUAL=code rqm edit RQM-1

If neither $VISUAL nor $EDITOR is set, the command fails with E-EDITOR-NOT-SET and exits 2.

The temporary copy

The copy is held in .rqm/edit/<pid>-<file name>, where <pid> is the process id and <file name> is the name part of the requirement file with .yaml kept. The copy is removed when the command succeeds, unless the write was refused because the file changed while the editor was open.

An invalid result

When the edited file has errors, it exits 2 and the file keeps the edited text. The diagnostics are reported, so you see what is wrong. This is not a rollback: the edited text is preserved, and you can fix the errors in the next edit.

error[E-UNKNOWN-FIELD]: The field 'duration' is not known
  --> requirements/RQM-1.yaml:15:3
[exit 2]

A changed uuid

The uuid of a requirement is its identity. Changing it breaks the hashes and the baseline. When a uuid changes, the command exits 2 with E-UUID-CHANGED and the file keeps the edited text.

error[E-UUID-CHANGED]: The uuid of RQM-1 was changed from 01a172b7-... to 12b283c8-...
  --> requirements/RQM-1.yaml:1:1
[exit 2]

An unchanged copy

When the editor exits with status 0 but the copy is unchanged, nothing is written and the command exits 0. The file and its modification time are unchanged.

An editor that exits with an error

When the editor exits with a non-zero status or is killed, the requirement file is not changed, the command fails with E-EDITOR-EXIT, and exits 3.

error[E-EDITOR-EXIT]: The editor exited with exit code 1, so RQM-1.yaml was not changed
[exit 3]

An interrupted write

If the requirement file is changed while the editor is open, rqm detects the change when it tries to write and refuses to overwrite it. The edited text is kept in the copy named in a help message, the file keeps the old text, and the command fails with E-WRITE-CHANGED.

error[E-WRITE-CHANGED]: The file requirements/RQM-1.yaml changed after rqm read it, so nothing was written
  help: Your edit is kept in .rqm/edit/1234-RQM-1.yaml
[exit 2]

rqm never removes the copy in this case, so that you can recover your edits.

Example

When no editor is set, the command fails:

$ rqm edit RQM-3
error[E-EDITOR-NOT-SET]: No editor is set: VISUAL and EDITOR are both unset or blank
[exit 2]

When the editor is set and the file changes, rqm writes and validates it:

$ VISUAL=code rqm edit RQM-3
edited RQM-3 (requirements/RQM-3.yaml)

Or when the file is unchanged:

$ EDITOR='vim' rqm edit RQM-3
RQM-3 is unchanged

Options

$ rqm edit --help
Open a requirement in your editor, then check the result

Usage: rqm edit [OPTIONS] <REQUIREMENT>

Arguments:
  <REQUIREMENT>  The id (`RQM-12`) or the uuid of the requirement

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.