RFC: Assessing impact of a clarified requirement?

[gregshue]

Migrated from #1806

From gregshue:

This is NOT a feature request. It is just an exploration discussion of a User Need.

As a system evolves it may grow to cover a larger context. Requirement statements may need to change text in order to retain their original meaning/scope. All existing requirements tracing to that changed statement need to be reassessed to see if the tracing still holds or their statement text also needs to be changed.

Thoughts?

From stanislaw:

The idea here was to implement a VERSION field on both a requirement node and its RELATIONS.

Let's say your node REQ-1 has VERSION: 1 and there is another node B that has a UID: REQ-2 and RELATIONS: UID: REQ1/VERSION: 1.

Now, you modify your requirement REQ-1 and bump its VERSION to 2. This will make the tool highlight you automatically that the REQ-2 now points to REQ-1 with an outdated link (because its version is still 1).

I myself didn't have time to think about this properly, I simply saw how the OpenFastTrace tool does it, so the credit for this approach goes to them.

The advantage of this approach is that you get very nice impact assessment, the disadvantage is that you have to maintain the versions everywhere if you want to implement this to 100%.

It is rather easy to implement this in StrictDoc, but we were blocked by some other ongoing issues like Composable Documents or recent ReqIF upgrades.

cc @kestewart @redcatbear

[gregshue]

I myself didn't have time to think about this properly, ...

This is not an urgent topic. Ponder as fits your priorities and interests.

This will make the tool highlight you automatically that the REQ-2 now points to REQ-1 with an outdated link (because its version is still 1).

There is probably a better term than "outdated". The child item may need to REQ-1 version 1 because REQ-1 version 1 is in a baseline that REQ-2 is constrained to use. Indicating that the item needs to be re-evaluated is distinct from the version it needs to reference.

@stanislaw Are you expecting the same version indication covers STATEMENT + RELATIONS, or that there are separate versions for each?

I'm sure some of this is related to how the SCM system is used to implement document control/baselining and item versioning. A project using Git for the SCM system also has questions about number of repositories, what is captured in and referenced through a sub-repo, and how are branches/cherry-picking used.

This discussion may provide usage recommendations for files in Git and document fragments in StrictDoc. I hope it will produce an Expected Model of Use guide.

[stanislaw]

I myself didn't have time to think about this properly, ...

This is not an urgent topic. Ponder as fits your priorities and interests.

I actually do want to implement this ASAP, we just have to get through the existing work queue.

This will make the tool highlight you automatically that the REQ-2 now points to REQ-1 with an outdated link (because its version is still 1).

There is probably a better term than "outdated". The child item may need to REQ-1 version 1 because REQ-1 version 1 is in a baseline that REQ-2 is constrained to use. Indicating that the item needs to be re-evaluated is distinct from the version it needs to reference.

This needs to be implemented in the command-line and web user interfaces anyhow. We will get to the point where a better term can be selected.

@stanislaw Are you expecting the same version indication covers STATEMENT + RELATIONS, or that there are separate versions for each?

Maintaining two separate versions for STATEMENT and node RELATIONS seems a bit too much of overhead to me, so I would stay with maintaining just one VERSION per node. Let me know if there are strong reasons for versioning RELATIONS separately.

I'm sure some of this is related to how the SCM system is used to implement document control/baselining and item versioning. A project using Git for the SCM system also has questions about number of repositories, what is captured in and referenced through a sub-repo, and how are branches/cherry-picking used.

I was hoping that the Zephyr project would drive our design of a proper repository structure but given the worlds of Sphinx/Doxygen/mlx traceability plugin, we may want to find another reference project, or we could anyway do an exercise with Zephyr.

This discussion may provide usage recommendations for files in Git and document fragments in StrictDoc. I hope it will produce an Expected Model of Use guide.

I am pretty sure that more than one optimal project structure could exist depending on a given project's requirements. If you have a specific project in mind, let's brainstorm on what could be done by StrictDoc to model those. If the effort is success, I would document it as a possible project structure implementation.

[gregshue]

I think Sphinx/Doxygen/mix will find this issue has many more layers (literally) than they are expecting and designed for.

Here is what I'm aware of.

1. Regulations must be captured into traceable items. These GUID-identified statements must be baselined for a particular version of regulations since they are updated cyclically. This baselining is independent of any relationships.
2. In order to meet the regulations around timely security updates (e.g., ETSI 303 645, RED, CRA, etc.), 3rd party components must (nearly?) be reusable by a product manufacturer to be a viable option for integration. 3rd party components will need to come with the requirements they meet, the relationships of those requirements through to the implementation, and the verification suite that the implementation meets those requirements. These requirements and relationships will be baselined before they get to the product manufacturer.
3. The product manufacturer will need to capture and baseline System Requirements. These requirements will need to trace back to Stakeholder Needs and Stakeholder Requirements (constraints), which should (must?) be in place at the time of baselining.
4. At some point many product manufacturers will field two systems at once: legacy and replacement. Each is captured in a separate document with separate relationships.
5. It is likely that the same regulations apply to both systems, so reusing the regulations is strongly desired.
6. It is likely that some of the same 3rd party components are used in both, so reusing the 3rd party component requirements/assumptions of use is strongly desired.
7. It is reasonable for a product manufacturer to reuse some proprietary subsystems between the two systems, so the same reuse need occurs internal to the product manufacturer.
8. It is expected that some of the requirements on a reusable component are not relevant for a particular integration. This means a requirements statement and all associated relationships must be removable/filterable, which leads to the removal of unjustified/"dead" code.

AFAICT, this:

• outlines the user needs for top-down and bottom-up workflows
• shows how statements have a lifecycle independent of relationships
• shows how statements and relationships are sometimes established and controlled (baselined?) by independent actors (which may need to impose separate access controls for each as well as for each document)
• shows that reuse of an individual statement version is strongly desired
• shows that reuse of an individual relationship to a statement version is strongly desired

Thoughts on this description of the problem space?

[redcatbear]

Hi, since OpenFastTrace was mentioned before, I can shed some light on why requirements have individual revision numbers there. @stanislaw is correct, the main idea behind this is that incrementing the revision number automatically shows the links to the covering item as outdated. Or "requiring reevaluation" as you very aptly put it.

The idea of course being that the requirement engineers should at a very least spend the time to check whether the coverage is forward-compatible. If it is, the only thing left to do is update the revision number in the coverage links.

As we all know, compatibility is not always guaranteed, the modification can cause a chain reaction. While that does not safe you from the work of doing the necessary updates, following the graph at least spells out what you have to do.

On the process side, introducing revision numbers for individual items requires some ground rules. E.g. that authors need to increment the number if there is a semantic change in a requirement. Of course fixing a typo or adding a rationale does not constitute a semantic change. One of the reasons why we did not simply use hashes (like in git). A hash tells you that there was a modification. But it cannot tell whether it must propagate through the coverage graph.