rqm create
rqm create
rqm create writes the file of a new requirement. It picks the next free number, gives the requirement a new uuid, and creates requirements/RQM-<n>.yaml. It does not open an editor.
rqm create --title <text> [--kind <name>] [--text <text>] [--acceptance <text>]... [--field name=value]...
Only --title is required. Everything else has a default, and the result is always a file that passes rqm check:
$ rqm create --title "Every sign-in is recorded" --field area=audit
created RQM-5 in requirements/RQM-5.yaml
uuid: <uuid>
it is a draft: replace the TODO placeholders, then run rqm check
$ cat requirements/RQM-5.yaml
schema: 1
uuid: <uuid>
id: RQM-5
kind: functional
title: Every sign-in is recorded
text: "TODO: describe the requirement."
acceptance:
- "TODO: describe how it is accepted."
verification:
- test
status: draft
fields:
area: audit
The status is draft and the text and the acceptance criterion are visible placeholders, so a requirement that was just created cannot be mistaken for a finished one. Open the file in your editor, write the text and the criteria, and change the status when the requirement is agreed.
The options
--kindchooses the kind. Without it the requirement has the default kind of the project. An undeclared kind is an error that lists the declared ones.--textand--acceptancegive the text and the acceptance criteria right away. Repeat--acceptancefor more than one criterion.--field name=valuesets a field of the kind. Repeat it for more fields, and for the entries of a field that is a list. The kind decides the type of each field, and what a field is is explained in Kinds and fields.
If the kind has a required field you do not give, nothing is written:
$ rqm create --title "Passwords expire"
error[E-MISSING-FIELD]: The field 'area' of kind 'functional' is missing, and no ancestor sets it
--> requirements/RQM-6.yaml:1:1
= help: The requirement was not created.
[exit 2]
$ rqm create --title "Passwords expire" --field area=bogus
error[E-FIELD-VALUE]: The field 'area' must be one of auth, sessions, audit, found 'bogus'
--> requirements/RQM-6.yaml:13:9
= help: The requirement was not created.
[exit 2]
$ rqm create --title "Passwords expire" --field area=auth --text "A password older than 90 days must be changed." --acceptance "A sign-in with an old password asks for a new one."
created RQM-6 in requirements/RQM-6.yaml
uuid: <uuid>
it is a draft: replace the TODO placeholders, then run rqm check
Numbers and safety
The new number is one more than the highest number in the project. It counts the requirements that were read and also the names of the files that could not be read, so a requirement with an error never gives its number away to another one. The file is created only if it does not exist, so create cannot overwrite a requirement, and when two people create a requirement at the same moment one of them gets E-CREATE-EXISTS and runs the command again.
Options
$ rqm create --help
Write the file of a new requirement
Usage: rqm create [OPTIONS] --title <TEXT>
Options:
--format <FORMAT> Output format. JSON is the stable contract [default: human] [possible values: human, json]
--title <TEXT> The title of the requirement
--kind <KIND> The kind. Defaults to the default kind of the project
--strict Treat warnings as errors for the exit code. The output itself does not change
--text <TEXT> The text of the requirement. Defaults to a placeholder
--acceptance <TEXT> One acceptance criterion. Repeat the flag for more. Defaults to a placeholder
--field <NAME=VALUE> A field of the kind, as name=value. Repeat the flag for more, and for the entries of a list field
--prefix <PREFIX> The prefix of the new id, such as CORE. Required when the project declares several
-h, --help Print help
The data of --format json is described in The JSON output.