UML dans un dépôt : Mermaid
L'export qui abandonne le plus et achète la seule chose que les autres ne peuvent pas : un diagramme qui vit à côté du code et change dans la même pull request.
5 min de lectureXMI 2.5.13 sur 3
01The trade, stated plainly
Mermaid is the worst of the three export formats at carrying a model and the only one of them that solves the problem most documentation actually has. XMI carries the metamodel; .qea carries the metamodel and the layout; Mermaid carries roughly what fits in a paragraph of text - and renders in a README without a build step.
That is the whole argument, and it is a good one. A diagram exported as PNG into a wiki is wrong within a quarter and nobody notices, because nothing about changing the code obliges anyone to look at it. A diagram in docs/architecture.md shows up in a diff when its file is touched, and a reviewer who can read the change can see the diagram disagree with it.
02What Mermaid can and cannot draw
| Element | Notation | What it means |
|---|---|---|
| Class diagram | Good | Classes, members, visibility, all six relationship kinds and multiplicities. The closest match to UML in the whole syntax. |
| Sequence diagram | Good | Participants, sync and async messages, activations, and alt, opt, loop and par blocks. |
| State diagram | Good | States, transitions with guards, composite states and history. |
| ER diagram | Good | Crow's foot cardinality and attribute lists. A close match to the ER article. |
| Use case diagram | Partial | Actors and cases, but no first-class include or extend. |
| Component, deployment, timing | Absent | No syntax at all. A flowchart approximation is possible and is not the same diagram. |
What is lost even in the good rows is worth naming: stereotypes, notes, constraints, and every trace of layout. Mermaid lays out its own diagrams, so the arrangement you spent an hour on does not survive - and for a diagram that is going to be regenerated on every change, that is a feature rather than a loss.
03Making it stick
Export the views a developer would actually open, which is almost never all of them. One class diagram of the core domain and one sequence diagram of the flow that everybody debugs is a better repository than fourteen files nobody reads.
Commit the Mermaid, not a rendered image. GitHub, GitLab and most static site generators render fenced mermaid blocks directly. An image checked in beside the source is a second copy that will disagree with it.
Regenerate rather than hand-edit. The moment somebody fixes a class name in the Markdown instead of in the model, the export has stopped being an export and the two versions begin to drift - which is the failure mode keeping a model current is entirely about.
In one line each
- 01Mermaid carries the least of the three formats and is the only one that lives in a diff.
- 02Class, sequence, state and ER map well; component, deployment and timing have no syntax.
- 03Stereotypes, notes, constraints and layout are all lost - and losing layout is fine here.
- 04Export the two or three views developers consult, not the whole model.
- 05Commit the text, never a rendered image, and regenerate rather than hand-edit.
04Questions fréquentes
Quels diagrammes UML Mermaid gère-t-il ?
Classes, séquence, états et cas d'utilisation ont des équivalents directs, et il existe aussi un diagramme entité-association. Composants, déploiement, temps, structure composite et les autres n'ont pas de syntaxe : un modèle qui en contient s'exporte partiellement, voire pas du tout.
Pourquoi exporter vers Mermaid s'il perd du détail ?
Parce que c'est du texte, et le texte va dans le dépôt. Un diagramme Mermaid apparaît dans le diff d'une pull request, se rend nativement sur GitHub et GitLab, et se relit en même temps que le changement qu'il décrit - le seul mécanisme qui garde durablement un diagramme vrai.
Mermaid remplace-t-il un outil de modélisation ?
Non. Mermaid dessine des diagrammes ; un outil de modélisation tient un modèle derrière plusieurs vues. Renommer une classe en Mermaid, c'est modifier un fichier ; la renommer dans un modèle met à jour toutes les vues qui la montrent. Réservez Mermaid aux vues qui doivent vivre dans le dépôt.
À lire aussi