From 29d9ca05e5dd72f6f6478f24a6b053d6dc43ded3 Mon Sep 17 00:00:00 2001 From: ewuerger Date: Wed, 3 Jan 2024 14:06:00 +0100 Subject: [PATCH] docs: Update documentation --- docs/source/configuration.rst | 49 ++++++++++------- docs/source/index.rst | 37 ++++++++----- docs/source/pipeline templates/gitlab.rst | 38 +++++++++++++ tests/data/model_elements/config.yaml | 66 +++++++++++------------ 4 files changed, 125 insertions(+), 65 deletions(-) create mode 100644 docs/source/pipeline templates/gitlab.rst diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 6dc13803..a4682b40 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -2,40 +2,51 @@ Copyright DB InfraGO AG and contributors SPDX-License-Identifier: Apache-2.0 -.. _config: +.. _capella2polarion-config: YAML ==== -To control the migration of model elements, you can use the following YAML -file. In this file, you can specify the layer and class type for matching -objects. If an item is a dictionary, it means there are work item links to be -migrated. Make sure to use the attribute names on the capellambse object -correctly. +To control the migration of model elements, the following YAML file serves as a +configuration for the capella2polarion service. In this file, you can specify +the layer, the type in Polarion, the class type for matching objects in +capellambse, the serializer to use. If an item is a dictionary, it means there +are work item links to be migrated. Make sure to use the attribute names on the +capellambse object correctly. .. literalinclude:: ../../tests/data/model_elements/config.yaml :language: yaml :lines: 4- The first section is a general configuration where you can set links to be -migrated for all class types. For example, ``parent`` and ``description_reference`` -are links that will be applied to all specified class types. Since ``Class`` is a -common class type that exists in all layers, links specific to ``Class`` can be -specified here to avoid duplication. +migrated for all class types. For example, ``parent`` and +``description_reference`` are links that will be applied to all specified class +types. Since ``Class`` is a common type that exists in all layers, links +specific to ``Class`` can be specified here to avoid duplication within the +file. + +.. _polarion-config: Polarion ======== In general, if an attribute is not configured, it will still be accepted and -created via the Rest API. However, to be able to make ``GET`` requests, you -need to configure your Polarion project correctly. The matching of diagrams and -model elements is done using the ``uuid_capella`` attribute, which needs to be -declared in the ``Custom Fields`` section. Simply choose ``All Types`` for this -attribute. +created via the Rest API but it will be handled as a plain string attribute. +However, to be able to make ``GET`` requests, you need to configure your +Polarion project correctly. For that there is the `Polarion DBS Project +Template`_ which includes icon, custom field and enumeration configuration for +a pleasant capella2polarion synchronization. + +.. _Polarion DBS Project Template: https://github.com/DSD-DBS/capella-polarion-template#polarion-dbs-project-template + +In the following are some requirements for the configuration if you don't want +to use the Project Template: + +The matching of diagrams and model elements is done using the ``uuid_capella`` +attribute, which needs to be declared in the ``Custom Fields`` section. Simply +choose ``All Types`` for this attribute. To have icons for your model elements, you need to declare the work item type -in the ``workitem-type-enum.xml`` file in the Polarion administration panel. -This file is an enumeration file where the work item type IDs should follow the -camel case pattern (e.g., ``operationalCapability`` for -``OperationalCapability``). +in the ``workitem-type-enum.xml`` file in the Polarion administration panel and +upload a 16x16 picture file. To generate clickable linked work items, you need to configure the link role enumerations in the ``workitem-link-role-enum.xml`` file. Here, the ID should diff --git a/docs/source/index.rst b/docs/source/index.rst index 0c194844..303ac391 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,20 +7,25 @@ capella2polarion A tool to migrate Capella content to a Polarion project as work items. -Diagrams --------- -Migrate diagrams from a diagram cache (pipeline artifact from a capella diagram -cache) job run to Polarion as work items. The whole folder with the -``index.json`` and the SVGs is needed. - -Model-Elements --------------- +Synchronization of Model-Elements +--------------------------------- + Migrate any model element from a ``capellambse.MelodyModel`` to Polarion as a -work item. With appropriate :ref:`configuration ` on Polarion and an -according config YAML file, any attribute on the capellambse object can be -migrated as a work item link if (and only if) the target object exists as a -work item already. In order to generate diagram references, make sure to -execute the model-elements migration after the diagram migration. +work item. Diagrams are taken from a diagram cache (pipeline artifact from a +`capella diagram cache`_) job run to Polarion as work items. The whole folder +with the ``index.json`` and the SVGs is needed for the diagram synchronization. +The SVG and a PNG of it are attached to the respective work item. + +With appropriate :ref:`configuration ` on Polarion +and an according :ref:`config YAML file ` for +capella2polarion any model element can be migrated from a Capella model to a +Polarion project. Attributes are migrated as links and text from requirements +and link groups are synchronized as custom fields. + +The synchronization works by comparing the checksum of work items. If they +differ the old will be patched by the new one. + +.. _capella diagram cache: https://github.com/DSD-DBS/capella-dockerimages/blob/main/ci-templates/gitlab/diagram-cache.yml .. toctree:: :maxdepth: 2 @@ -28,6 +33,12 @@ execute the model-elements migration after the diagram migration. configuration +.. toctree:: + :maxdepth: 2 + :caption: CI/CD Template: + + pipeline templates/gitlab + .. toctree:: :maxdepth: 3 :caption: API reference diff --git a/docs/source/pipeline templates/gitlab.rst b/docs/source/pipeline templates/gitlab.rst new file mode 100644 index 00000000..060787de --- /dev/null +++ b/docs/source/pipeline templates/gitlab.rst @@ -0,0 +1,38 @@ +.. + Copyright DB InfraGO AG and contributors + SPDX-License-Identifier: Apache-2.0 + +GitLab CI/CD pipeline Template +------------------------------ + +The capella2polarion library can be used in a CI/CD pipeline. For that the +following template can be used inside the `.gitlab-ci.yml` file: + +.. literalinclude:: ../../../ci-templates/gitlab/synchronise_elements.yml + :language: yaml + :lines: 4- + +A `.gitlab-ci.yml` with a capella2polarion synchronization job could look like +this: + +.. code:: yaml + + include: + - remote: https://raw.githubusercontent.com/DSD-DBS/capella-dockerimages/${CAPELLA_DOCKER_IMAGES_REVISION}/ci-templates/gitlab/diagram-cache.yml + - remote: https://raw.githubusercontent.com/DSD-DBS/capella-polarion/ci-templates/gitlab/synchronise_elements.yml + + default: + tags: + - docker + + workflow: # Control job triggering + rules: + - if: $CI_COMMIT_BRANCH == "main" # execution only on main + + variables: + CAPELLA_VERSION: 6.1.0 + ENTRYPOINT: model.aird + CAPELLA2POLARION_PROJECT_ID: syncproj + CAPELLA2POLARION_MODEL_JSON: '{"path": "PATH_TO_CAPELLA"}' + CAPELLA2POLARION_CONFIG: capella2polarion_config.yaml + CAPELLA2POLARION_DEBUG: 1 diff --git a/tests/data/model_elements/config.yaml b/tests/data/model_elements/config.yaml index 1bed2569..905adcbe 100644 --- a/tests/data/model_elements/config.yaml +++ b/tests/data/model_elements/config.yaml @@ -2,43 +2,43 @@ # SPDX-License-Identifier: Apache-2.0 "*": # All layers - - "*": # All class types - - parent # Specify workitem links - - description_reference # Custom attribute - - Class: - - state_machines - - Diagram: - - diagram_elements - - Constraint + - "*": # All class types + - parent # Specify workitem links + - description_reference # Custom attribute + - Class: + - state_machines + - Diagram: + - diagram_elements + - Constraint oa: # Specify below - - OperationalCapability: # Capella Type with references - - involved_activities # Specify workitem links - - involved_entities + - OperationalCapability: # Capella Type with references + - involved_activities # Specify workitem links + - involved_entities - - OperationalActivity # Capella Type w/o references - - OperationalEntity # Custom Type maps to Entity - - OperationalInteraction # Custom Type maps to FunctionalExchange - - CommunicationMean - - Class - - StateMachine + - OperationalActivity # Capella Type w/o references + - OperationalEntity # Custom Type maps to Entity + - OperationalInteraction # Custom Type maps to FunctionalExchange + - CommunicationMean + - Class + - StateMachine sa: - - SystemComponent: - - allocated_functions - - SystemActor: # Custom Type that doesn't exist in Capella - - allocated_functions - - SystemFunction - - ComponentExchange: - - allocated_functional_exchanges - - ComponentPort - - FunctionalExchange: - - exchanged_items - - ExchangeItem - - Class + - SystemComponent: + - allocated_functions + - SystemActor: # Custom Type that doesn't exist in Capella + - allocated_functions + - SystemFunction + - ComponentExchange: + - allocated_functional_exchanges + - ComponentPort + - FunctionalExchange: + - exchanged_items + - ExchangeItem + - Class pa: - - PhysicalComponent: - - allocated_functions - - PhysicalActor: - - allocated_functions + - PhysicalComponent: + - allocated_functions + - PhysicalActor: + - allocated_functions