DSD-DBS/capella-rm-bridge

Improvements of documentation and associated Capella model

Opened this issue · 0 comments

MS34449 commented

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?