Skip to main content

TRG 1.04 - Diagrams as code / Editable static files

StatusCreatedPost-History
Active12-Dez-2023move from Draft section to Active TRG's
Draft20-Sept-2023created initial Draft
Edited24-Okt-2023add draw.io as possible solution for static .svg-files

Why​

To have an easier approach to update current diagram files and have a better overview of the changes within the diagrams, and we can ensure that all diagrams follow the same standards. This helps people to understand our workflows within our products and make it easier to understand the product itself. Also updating the static files will be easier and faster to do for every committer or maintainer of our repositories.

This includes:

  • diagrams
  • flowcharts
  • sequence diagrams
  • state diagrams
  • gantt charts
  • etc.

Description​

All diagram files must be either using code to generate diagrams, or stored as .svg file within our repositories. After a committers decision there are 2 languages accepted, either PUML or Mermaid. If you're using a specific tool like Draw.io, describe how you created it and document the creation or modification process in your documentation files.

Goal of this TRG is to have a better overview of the changes within the diagrams, and we can ensure that all diagrams follow the same standards:

  • we need to contribute editable source files for diagrams
  • we need to describe the used tools that need to be usable by anyone without the need of a licence (prefer open source tools)
  • used tools for diagrams should be OS independent
  • we need to describe the used tools and the version of the tool and the creation process of the diagrams

These diagram code files (.puml,.mmd,.mermaid) and / or static diagram .svg files must be stored within the docs/ folder as described in TRG 2.03.

In addition to this you can integrate mermaid diagrams also directly into your markdown files as code snippets.

PlantUML / Mermaid / Markdown snippets​

PlantUML example​

@startuml
(First usecase)
(Another usecase) as (UC2)
usecase UC3
usecase (Last\nusecase) as UC4
@enduml

example-as-image

Mermaid example​

flowchart TD
    A[Committer] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[Mobile Phone]
    C -->|Three| F[fa:fa-car Car]

example2-as-image

Example Mermaid into Markdown​

```mermaid
flowchart TD
    A[Committer] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[Mobile Phone]
    C -->|Three| F[fa:fa-car Car]
```

Draw.io Example​

alice-bob-as-image

This image was generated with draw.io and stored as .svg file within the /docs folder in our repository. A description how to modify and update our diagrams is provided in our documentation in the /docs folder.

Example explanation how the diagram was modified:

  • checkout the repository
  • open the docs/alice-bob-drawio.svg file with draw.io
  • modify the diagram
  • save the diagram as .svg file
  • ... pr process ...
![alice-bob-as-image](../../../docs/images/alice-bob-drawio.svg)

Technical requirements​

GitHub workflows​

Reusable workflows for each language can be found here: