The RM Bridge currently supports two ways of distinguishing whether an "item" is a RequirementsFolder or a Requirement. The first one is through the presence or absence of the children key, which is – as far as I'm aware – the recommended way (where presence of the key, even if it contains an empty list, means it's a folder). The second way is to declare the special attribute "Type" to have the value "[Folder]" (notice the casing and brackets).

The latter is a left-over from one specific importer, which had (or still has?) a bug that made it not produce empty children lists for folders. This behavior should be deprecated and eventually removed, so that presence/absence of the "children" key is the only discriminator. ("There should be one-- and preferably only one --obvious way to do it.")

Make validity of computed ChangeSets a target of these tests.

The "full documentation" link in the README is dead and leads to a 404: https://dsd-dbs.github.io/rm-bridge

By various comments and requests from the review by @Wuestengecko it is clear that we'll need to document how the snapshot is transferred to a ChangeSet that will ultimately alter the model.

For e.g. using the GIT-URL in the config (model Section) isn't supported and so on.

Hi there,

the RM Bridge documentation and the associated Capella model can be improved - here are the suggestions:

Introduction

• "... So all this library does is to convert the data exported from the RM software to a Snapshot and calculate a ChangeSet based on it. This ChangeSet can then be applied to a Capella Model via the capellambse headless model API."

• explain the basic architecture. E.g. "RM Bridge consists of two main parts: RM Tool Connector (specific for a particular RM tool, e.g. CodeBeamer, Polarion etc.) and Capella Connector. These parts exchange data using a YAML syntax suitable for representing ReqIF data (Snapshot). Currently only the RMTool2Capella direction is supported."

• mention also the sync triggering logic, which is out of scope of the RM Bridge itself - it is customisable within the integration, i.e. a selection, combination and configuration of the available sync triggering options like manual, schedule (cron, GitLab schedule), event (git commit, T4C CDO history log event ...).

• also mention, that the T4C is an optional part, because for some projects storing the Capella model in git would suffice

Updates in the Capella LAB diagram and renaming of things:

• ReqModules -> Capella ReqModules
• explain in a note or so that the term Tracker,, although used in the RM Bridge docs for any RM tool is actually only used by CB. Polarion does not use it, it mentions just a list or table of work items ... also refer that explanation in ChangeSet documentation TrackerChange-"Maybe called module in different RM tools."
• Capella RM Bridge -> Capella Connector (to be consistent with "RM Tool Connector" and also to be ready for the reverse direction Capella2RMTool, it is not just a ModelModifier)
• instantiate MelodyModel -> "get latest Capella model"

Further changes in the Capella model:

• remove trigger model update as it is not part of SoI nor does it interact with it (see above explanations about sync triggering logic)
• add func. exchange between Tracker Contents and provide Tracker CRUD
• add function convert Tracker Contents to Snapshot
• rename SyncActions to ChangeSet

• In the Capella RM Bridge model update also the Scenario diagram acc. to the above changes made in the model

Snapshot :

• items - attributes: comment says "Fields for a Folder" - could it be explained?
• could a better explanation be added to the following docstrings?
  • EnumerationDataTypeDefinition - "proxy objects on the fly" ?
  • EnumerationValueAttribute - duplicit docstrings?
  • chapter Enumaration Data Types ... - this explanation is not intelligible, not easy to grasp - could it be reworded by expanding on the semantics of the example there?

Problem Definition

Currently the RM Bridge identifies capellambse.reqif.Folders iff there are non-empty children in the snapshot item. (Once upon a time there was a special case where a folder_hint boolean variable was set to True if an attribute combination type="Folder" was met. This was removed.) For the following live-doc Preamble and General Assumptions are just headings without any children work items. Therefore they won't have children in the snapshot and the RM Bridge identifies them as capellambse.reqif.Requirements.

This causes a false order in the Capella model:

As you can see the Introduction folder is written into the xml file after General Assumptions even if the order was still correct in the ChangeSet but they are divided into requirements and folders.

With my understanding of how capellambse registers requirements and folders on a capellambse.reqif.CapellaModule and how declarative modelling (decl) works, there's currently no way to control the creation order when using decl. Letting decl create folders first and then requirements could fix the problem, but I don't think that this specific behavior should be implemented in capellambse.

Solution proposal

With my understanding the order of model object creation with different class types (xsi-types) using decl can't be controlled in capellambse. Not with the current DirectProxyAccessor infrastructure. But that is a different problem that was revealed by this one. This problem is caused by a miss-identification of the workitem as a requirement. That caused the division of it into another bucket (requirements) and the order is only kept inside each bucket (folders, requirements). So I think that if these headings would've been identified as folders, the order would've been kept.

Folder identification by configured type (folder_hint revival)

I see a feature where the user specifies a special capellambse.reqif.RequirementType (as type) in the config and marks all work items with this special type as to-be-identified as folders. With this, a folder_hint boolean can be set in the TrackerChange.yield_requirements_create_actions (and probably also TrackerChange.yield_requirements_mod_actions) in capella_rm_bridge.changeset.change.py such that these special work items will be rendered as folders w/o any children.

RM content revision number:
r2551

Several docstrings try to reference external classes (mostly from https://github.com/DSD-DBS/py-capellambse), but these links are broken and get stripped from the generated docs. Some links are genuinely broken anyways, but in all cases Intersphinx (or a suitable alternative) needs to be set up for this project in order to make these links work.

It might become interesting to track the snapshot format version. But that's more something to keep in mind for the future, when (if) this project becomes more widely used, and if there are other non-backwards-compatible changes in the format.

Originally posted by @Wuestengecko in #37 (comment)

If any exception was raised during the calculation this ChangeSet shouldn't be written. Additionally the option to skip the calculation for all modules if one had errors is a nice to have if modules depend on each other. This behavior is protection against synchronization of erroneous data from external tools.

Following our coding guideline (Google style) we don't use relative imports like
from . import (...)

See

• https://github.com/DSD-DBS/rm-bridge/blob/340309874b90962615ac79ae927840c8e08ab06e/rm_bridge/changeset/__init__.py
• https://github.com/DSD-DBS/rm-bridge/blob/340309874b90962615ac79ae927840c8e08ab06e/rm_bridge/changeset/change.py

On any event type for an object no child events are reported. I.e. if a root level folder was removed only this event is stored and mentioned in the report. All child deletions should be noted too.

Refer to:

https://github.com/DSD-DBS/rm-bridge/blob/340309874b90962615ac79ae927840c8e08ab06e/rm_bridge/changeset/change.py#L30

_ATTR_VALUE_DEFAULT_MAP: cabc.Mapping[str, type] = {
    "String": str,
    "Enum": list,
    "Date": datetime.datetime,
    "Integer": int,
    "Float": float,
    "Boolean": bool,
}

Why is a datetime mapped to a date?

I would change that to

_ATTR_VALUE_DEFAULT_MAP: cabc.Mapping[str, type] = {
    "String": str,
    "Enum": list,
    "Date": datetime.date,
    "Date-time": datetime.datetime,
    "Time": datetime.time,
    "Integer": int,
    "Float": float,
    "Boolean": bool,
}

In order to know which model the calculated ChangeSet is for, which Capella version , which capellambse version and what revision, revision hash and branch (if versioned model) was used, this information should be included into the ChangeSet.

It should look like the following:

capellambse: 0.5.15
model:
  url: [email protected]/example.git
  version: 12345678...
referencing: implicit
generator: Capella-RM-Bridge v1.0.0
---
...

referencing will inform about the type of the ChangeSet. If referencing: explicit is set it is expected that the ChangeSet includes all implicit changes as well (actions to references).