Dlaczego przechowywać diagramy razem z projektem#
Diagram związany z kodem, wymaganiami lub dokumentacją powinien być odnajdywalny razem z właściwym projektem. Repozytorium pozwala wiązać zmianę diagramu ze zmianą kodu lub opisu, prowadzić przeglądy i wracać do poprzednich wersji. Warunkiem jest jasne wskazanie, który plik jest źródłem prawdy.
Plik źródłowy może być tekstem PlantUML lub Mermaid, edytowalnym projektem narzędzia graficznego albo eksportem modelu CASE. PNG, SVG i PDF są przydatnymi wynikami do odczytu, ale nie zawsze zawierają dane potrzebne do pełnej edycji. Zachowaj źródło, jeśli oczekujesz dalszych zmian.
Źródło i wygenerowany obraz#
W procesie diagram-as-code źródło tekstowe można renderować do SVG lub PNG przy każdej zmianie. W przypadku modelera graficznego plik projektu przechowuje model, a obrazy są eksportowanymi widokami. Oba podejścia mogą działać z repozytorium, ale różnią się czytelnością diffów, konfliktem przy równoczesnej edycji i możliwością automatyzacji.
Zespół może przechowywać zarówno źródło, jak i wygenerowany obraz, jeżeli obraz jest potrzebny do wyświetlenia bez dodatkowego renderera. Należy wtedy ustalić, czy obraz jest sprawdzany w repozytorium, generowany automatycznie, czy pomijany jako artefakt odtwarzalny. Nie utrzymuj dwóch niezależnych, ręcznie edytowanych kopii diagramu.
Proponowana struktura katalogów#
Prosta struktura może rozdzielać diagramy według modułu lub tematu, na przykład docs/uml/, docs/uml/zamowienia/ i docs/uml/platnosci/. Układ powinien odzwierciedlać nawigację w projekcie i skalować się wraz z liczbą widoków. Unikaj katalogu z setkami anonimowych plików i nie umieszczaj kopii tego samego diagramu w wielu miejscach bez wyjaśnienia, która jest nadrzędna.
Nazwy plików powinny być stabilne i opisowe. Dodaj w źródle lub obok krótki opis celu diagramu, właściciela, powiązany obszar i ewentualne ograniczenia. Ustal format i rozszerzenie pliku, konwencję tytułów, nazwy eksportu oraz ścieżkę do pliku graficznego używaną przez dokumentację.
Przegląd zmian i konflikty#
Tekstowy diagram pokazuje w diffie konkretne zmiany deklaracji i relacji, lecz nie zawsze ujawnia wpływ wizualny. Obraz pozwala zobaczyć układ, ale zmiana pozycji węzłów może powodować duży, mało informacyjny diff. W przeglądzie należy oceniać oba aspekty: semantykę źródła oraz czytelność wyrenderowanego wyniku.
Pliki graficznych modelerów mogą być tekstowe, binarne lub mieszane. Nawet tekstowy plik może być trudny do scalenia, jeśli wiele osób edytuje te same elementy. Ustal, czy diagramy blokują się na czas edycji, rozdzielają na moduły, scalają narzędziem producenta czy zmiany wykonuje jeden właściciel. Rozwiązuj konflikt w modelu źródłowym i ponownie eksportuj obrazy, zamiast ręcznie dobierać dwie wersje PNG.
Automatyczne renderowanie#
Pipeline może instalować ustaloną wersję renderera, generować grafiki i sprawdzać, czy wyjście odpowiada źródłu. Zapisz konfigurację, wersje zależności, czcionki i ustawienia stylu, jeśli wpływają na wynik. Zadbaj, by proces działał lokalnie oraz w CI w taki sam sposób. Zmiana wersji renderera może zmienić układ, nawet gdy treść diagramu jest identyczna.
Wybierz, czy CI ma tylko sprawdzać składnię, tworzyć artefakty, czy blokować łączenie zmian, gdy wygenerowany obraz nie został zaktualizowany. Sprawdzenie składni nie zastępuje kontroli merytorycznej i wizualnej. Wydziel poufne diagramy i upewnij się, że renderer nie wysyła kodu do zewnętrznej usługi bez zgody organizacji.
Dostęp, poufność i kopie zapasowe#
Diagramy mogą ujawniać topologię infrastruktury, nazwy systemów, mechanizmy kontroli dostępu, integracje i słabe punkty. Repozytorium powinno mieć adekwatne uprawnienia, zasady retencji i procedurę usuwania sekretów. Nigdy nie zapisuj poświadczeń ani prywatnych kluczy w diagramie.
Ustal, które treści mogą trafić do publicznego repozytorium, hostowanego rendererа lub zewnętrznego serwera. Sprawdź licencje oraz zasady przechowywania danych. Kopie zapasowe obejmują przede wszystkim edytowalne źródła i ustawienia potrzebne do odtworzenia wyników; same obrazy nie wystarczą.
Reguły zespołowe#
Dokumentuj minimalne zasady: lokalizację źródła, nazewnictwo, format, właściciela, odbiorców, warunek aktualizacji, metodę renderowania i proces przeglądu. Aktualizuj diagram, gdy zmienia się opisana architektura lub zachowanie, a nie przy każdej kosmetycznej zmianie kodu. Połącz diagram z właściwą zmianą projektu i wskaż, do jakiej wersji systemu się odnosi.
Wybierz podejście dopasowane do grupy. Kodowy format sprawdza się przy częstych przeglądach tekstowych i automatycznym generowaniu; plik graficzny może być wygodniejszy dla wspólnej, ręcznej edycji; centralny modeler odpowiada procesom wymagającym repozytorium elementów i śledzenia. Kluczowa jest odtwarzalność oraz jednoznaczne źródło prawdy.