Implementation concept for "mapped" documents to address the multi-parent problem

[ckolumbus]

This PR implements the notion of a "mapped" document which addresses (to some extend) the multi-parent problem.

I'm coming from a medical device software development environment and have similar requirements as mentioned in #509 . We are using Caliber for most of the requirements and the idea is derived from how we define traces there. It depends on what exactly you need to achieve, but please read on and comment on the proposal

Context:

• Assume we have the following tree Feature_Req <- SW_Req <- SW_Test, and now we have a TRA (thread and risk analysis) which "generates" new mitigation requirements based on the Feature_Req.
• I'm also assuming now that the following is sufficient: EVERY requirement from TRA needs to be picked up by the SW_req (implemented) , but NOT EVERY SW-Req needs to trace to a TRA requirement. In our case this holds true because we need to make sure that all TRA elements are implemented, but not every SW Req actually need one
• on a side note: in order to verify that all TRA requiremetns a tested, a new TRA_Test document could be created as a child to the TRA itself.
• the main difference to normal tracing in doorstop is, that in for normal trace EVERY requirement in a child document needs to trace to a parent req, unless it is derived. Here it is more saying: "no matter what you do elsewhere in the mapped document, you need to pick up all my requirements at least somewhere". This loosens the tight tracing requirements that would break with multi-parent approach.

If the assumptions are above are valid, then the implementation sketch looks like this

1. let's define a document that holds the TRA: normal document dependencies, child doc of Feature_Req
2. configure an "mapped_to" attribute in the TRA document that lists the documents that need to pick up all the requirements from the TRA, in our case this would list "SW_Req"
3. as a sanity check we could make sure that the mapped document is neither a parent of a child of the current document (direct or indirect, to avoid trace loops) - not done yet
4. when validating document we check for the existence of the mapped_to attribute and validate whether all items from this document are actually picked up by the "mapped_to" document(s). It's not checked, as in the normal case, whether every child document requirement will have a link to this "mapped" parent

Main effort is in the item_validator. In addition, a new attribute on document level has been introduced ( and because i need it for something else, also a general "custom attribute" feature similar to items).

All existing tests are working fine, no tests for the new implementation exist yet. Please review and if this would be a candiate for integration into the upstream repo then the tests and doc updates follow.

Addresses aspects of: #309 #509

[codecov-commenter]

Codecov Report

Merging #569 (4cecf49) into develop (44a2751) will decrease coverage by 0.28%.
The diff coverage is 62.50%.

@@             Coverage Diff             @@
##           develop     #569      +/-   ##
===========================================
- Coverage    95.43%   95.14%   -0.29%     
===========================================
  Files           35       35              
  Lines         4618     4658      +40     
  Branches       880      924      +44     
===========================================
+ Hits          4407     4432      +25     
- Misses         129      139      +10     
- Partials        82       87       +5     

Impacted Files	Coverage Δ
doorstop/core/validators/item_validator.py	79.60% <54.54%> (-9.11%)	⬇️
doorstop/core/document.py	96.38% <66.66%> (-0.36%)	⬇️
doorstop/core/tree.py	95.75% <80.00%> (+0.03%)	⬆️
doorstop/core/item.py	97.07% <100.00%> (+0.01%)	⬆️
doorstop/cli/commands.py	97.22% <0.00%> (-0.31%)	⬇️
doorstop/settings.py	100.00% <0.00%> (ø)
doorstop/core/publisher.py	97.18% <0.00%> (ø)
doorstop/server/main.py	93.43% <0.00%> (+2.18%)	⬆️
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 44a2751...4cecf49. Read the comment docs.

[ckolumbus]

@jacebrowning could you please have a look? or let me know who else can help with driving this forward.

[jacebrowning]

@ckolumbus I'd recommend pulling in folks from the relevant issues to see if this approach will work for their respective industries.

[ckolumbus]

I already asked there, not much feedback so far .... but I'll try to get some more input on the process aspect👍

From your side any implementation or concept feedback?

[stanislaw]

Hi @ckolumbus , here is feedback from someone who is the author of a similar tool.

The problem that you are solving is very clear to me and it makes complete sense: by making your TRA document's mapped_to field to be set to SW_REQ, you want to make sure that every TRA requirement is implemented somewhere in the SW_REQ, i.e. by the requirement items of the SW_REQ ("each requirement of TRA should be implemented by one or more SW_REQ requirements").

StrictDoc does not implement this feature yet but I would definitely consider doing it at some point if there was a need.

Here are my thoughts:

• While the mapped_to behavior seems clear and practical to me, I don't see how this feature would in any way solve the problem of multiple parents. As far as I understand, the multiple parents problem is related to the fact that you want to be able to link a requirement item to one or more parent requirement items. In my experience, this happens very often that one requirement may refine multiple parent requirements from more than one parent documents (in your example, this would be that a software requirement refines one parent feature requirement and one TRA requirement). As of today, StrictDoc supports child-to-multiple-parents Parent link type, and I am quite sure that someone should implement multiple parents in Doorstop. ReqIF model also supports SPEC-RELATION concept which allows linking requirements to multiple parent requirements as well as creating custom relation types.

• At work, I don't use Doorstop or StrictDoc (mainly because both tools don't have a powerful GUI which is an absolute must-have for non-software colleagues). Instead, our company uses Confluence for documentation and there we use YOGI, a requirements plugin. On top, we put our custom Python automation to export the YOGI requirements database to a large Excel table from which we generate an HTML report where each and every document of our requirements tree has associated statistics where we can see: Document X: A requirements total, B requirements are refined (C%) which to some extent ensures that we don't miss any of the X requirements and they will not get refined. This way, we don't have an automatic validation of the 100% fact like your mapped_to would do, but we definitely can see how far are we on the way of refining all requirements that we need.

• If the above comment is valid, i.e. that mapped_to and multiple parents are orthogonal to each other, I certainly see both features to solve real-world problems. I don't have time to revisit your implementation of it in Doorstop, but I certainly support the concept of mapped_document 👍

[stefanoco]

Everything good here from my point of view, looking forward at wider adoption in FuSa relevant design processes with this addition.

[ckolumbus]

@stanislaw could you maybe provide some more details on the expected behavior of the "multi-parent" mode.

AFAIU according to the existing doorstop tracing philosophy every child requirement would need to trace to at least one requirement in each of the parent docs. Is this the expected behavior? I'm working in a medical multi-system environment with strict tracing requirements, but I've not seen this specific use case in our process.

What we rather have is that higher level documents assign specific (==individual) requirements to (sub-)systems. So the 'mapped_to' concept is actually executed on a per-requirement basis, not of full document scop. But again, I believe this is not what you have in mind.