Parents and inheritance
Parents and inheritance
Requirements relate to each other in two ways. A parent says that a requirement refines another one, and it makes a tree. links say that two requirements are related in some other way, and they make a graph.
References
A requirement is referred to by its id (RQM-1) or by its uuid. parent, links, and the argument of rqm show take either. A reference that names no requirement that could be read is an error, and the message tells you to check that the file of the target has no errors of its own:
$ rqm check
checked 3 requirements (loaded 3 of 4 discovered requirement files)
error[E-REF-UNKNOWN]: The reference RQM-9 does not name a requirement
--> requirements/RQM-2.yaml:10:9
= help: No requirement with this id or uuid could be read. Check that its file has no errors.
[exit 2]
Parents
parent: "RQM-1" says that this requirement refines RQM-1. A requirement has at most one parent. The parents of a requirement, its parent’s parent and so on, are its ancestors, and there can be at most four of them. A parent chain that loops back on itself is an error that names every requirement in the loop:
$ rqm check
checked 2 requirements (loaded 2 of 4 discovered requirement files)
error[E-INHERIT-CYCLE]: The parent chain loops through RQM-3, RQM-4
--> requirements/RQM-3.yaml:12:9
[exit 2]
rqm show lists the children of a requirement, so you can walk down the tree from any requirement:
$ rqm show RQM-1
RQM-1 Users can sign in
uuid: <uuid>
kind: functional
status: approved
priority: must
verification: test
file: requirements/RQM-1.yaml
bytes: <hash>
effective: <hash>
presentation: unverified
baseline: disabled
text:
A user who gives a valid name and password gets a session.
acceptance:
- A valid name and password give a session.
- A wrong password gives an error and no session.
tests:
- sessions::tests::sign_in_with_a_valid_password
- sessions::tests::sign_in_with_a_wrong_password
fields:
area: auth
children:
- RQM-2 Sessions expire
linked from:
- RQM-4 Sign-in attempts are rate limited
note: rqm shows that the evidence meets the declared policy. It does not show that the tests are adequate.
Inheritance
Some values do not have to be written on every requirement. A requirement that does not write its priority gets it from its nearest ancestor that does, and when no ancestor does, from defaults in rqm.yaml, and when that has none, it has no priority. The order is always the same:
- the value the requirement writes,
- the value of the nearest ancestor that writes one,
- the default of the project,
- nothing.
priority is the only core key that is inherited. A field of a kind is inherited when its declaration says inheritable: true, and then the default of the field is the last step.
rqm show says where each resolved value came from, so there is never a doubt about why a requirement has the priority it has:
$ rqm show RQM-2
RQM-2 Sessions expire
uuid: <uuid>
kind: functional
status: approved
priority: must (inherited from RQM-1)
verification: test
file: requirements/RQM-2.yaml
bytes: <hash>
effective: <hash>
presentation: unverified
baseline: disabled
text:
A session ends a fixed time after it was granted.
acceptance:
- A session that is 30 minutes old is refused.
fields:
area: sessions
parent: RQM-1 Users can sign in
note: rqm shows that the evidence meets the declared policy. It does not show that the tests are adequate.
$ rqm show RQM-3
RQM-3 Passwords are never logged
uuid: <uuid>
kind: constraint
status: approved
priority: should (default)
verification: inspection
file: requirements/RQM-3.yaml
bytes: <hash>
effective: <hash>
presentation: not_applicable
baseline: disabled
manual: declared (an assertion by the author of the requirement, which rqm cannot check)
text:
No log line, at any level, contains a password.
acceptance:
- Nothing in the log output matches a password used in the tests.
evidence:
Read every logging call at the October review.
note: rqm shows that the evidence meets the declared policy. It does not show that the tests are adequate.
RQM-2 writes no priority and takes must from RQM-1. RQM-3 has no parent and no priority of its own, so it takes the default, should.
Because inheritance is part of the meaning of a requirement, changing the priority of a parent changes the effective hash of all its children. A child whose ancestor has an error is left out too, with a diagnostic that says which ancestor is the problem, since its resolved values cannot be known.
Links
links: ["RQM-1"] records that a requirement is related to another one. rqm gives a link no meaning of its own: it does not matter in which direction you write it, rqm never adds the opposite link to the other file, and a link does not change how anything is inherited. rqm show displays the links of a requirement and, as linked from, the requirements that link to it:
$ rqm show RQM-4
RQM-4 Sign-in attempts are rate limited
uuid: <uuid>
kind: functional
status: draft
priority: may
verification: test
file: requirements/RQM-4.yaml
bytes: <hash>
effective: <hash>
presentation: unverified
baseline: disabled
text:
A name that failed five times in a row is refused until it is reset.
acceptance:
- The sixth attempt after five failures is refused, even with the right password.
fields:
area: auth
links:
- RQM-1 Users can sign in
note: rqm shows that the evidence meets the declared policy. It does not show that the tests are adequate.