Używam komputerów od wielu lat. Jestem dinozaurem, zaczynałem w latach 90.

Dla wielu osób to już nie senior developer tylko grandfather developer.

Pomijając etykiety prędzej czy później na tym PC zawsze robił się błaga.

Sprostuję. Ja robiłem bałagan. Najprościej było wrzucić stary dysk do katalogu w nowym i po problemie.

Do dzisiaj mam takie zasoby…

Teraz wyobraź sobie bajzel w dokumentacji architektury… Nie możesz do tego dopuścić.

Dlatego pomimo wymienienia kilku sposobów na utrzymanie ADLa w moim poście tutaj.

Najlepiej jak użyjesz systemu kontroli wersji i automatyzacji, jaką daje np. adr-tools → więcej o narzędziu tutaj.

GIT

Dla mnie nie ma innego wyboru. Odkąd nauczyłem się używać w konsoli + VIM xD. To unikam innych narzędzi. Polecam i Tobie konsole GITa. Działa w niej wiele poleceń z linuxa. Jeżeli masz Windowsa, to może być dodatkowy atut ;).

No tu już pewnie się domyślasz, że polecam repo GITa jako narzędzie do utrzymania ADLa.

Jako że przeważnie mamy więcej możliwości w danej chwili. To pomimo wyboru systemu kontroli wersji nadal otwierają się dylematy.

A to osobne repo dla dokumentacji i kodu?

A może wszystko razem?

Odpowiedź jak dla mnie — to zależy — od Ciebie i teamu.

Dla mnie naturalnym wyborem jest utrzymanie dokumentacji architektury przy projekcie. W tym samym repozytorium.

Konwencja.

Zanim jednak przejdę do konkretów. Może trochę o konwencji, jaką możesz przyjąć.

To ponownie tylko moja sugestia, ale zainteresuj się Conventional Commits. Jest to pewna konwencja pisania commit message. Taki commit, ma pewne oznaczenie. Sugeruje ono, co tam się znajduje. Czy to jest fix, feature, refactor, test itd. Jeżeli się tego będziesz trzymał. To będzie to też pomocne przy ograniczeniu rodzaju zmian w jednym commicie. By nie pchać wszystkiego na raz tylko testy osobno, kodzik osobno itd.

Ja proponuje wzbogacenie CC o nowe oznaczenia:

• devops — wiadomo jakieś pipeliny, templatki itd.
• adl lub adr - opis architektury * arch — zmiana architektury np. aktualizacja modelu C4 → więcej o C4.

Takie oznaczenia ciekawie wyglądają podczas wyświetlenia listy commitów.

O tak… Po instalacji powinieneś mieć dostęp do polecenia adr-tools w Command Palette.

I tak…

Przykładzik.

Teraz pozostaje już tylko utworzyć folder (doc/adl) na dokumentację architektury i utrzymywać tam ADRki.

Możesz skorzystać z templatki i VSCode. Nawet jak używasz innego narzędzia, które nie wspiera templatek ADL. To możesz dla samej architektury użyć VSCode do ich utrzymania.

Więcej o templatkach w moim poprzednim wpisie.

Same polecenia GITa to już banały:

• git add -p /doc/adl - dodanie nowych ADRów wraz z przeglądem zmian (parametr -p)
• potwierdzanie zmian (dla polecenia wyżej) odpowiednio y - yes, n - no
• git commit -m”adr: add new adr entry for CQRS”
• na koniec git push…

I tak oto łączysz GITa, Conventional Commits i ADL.

Jeszcze tylko Diagram as Code i wszystko jest w jednym miejscu.

PS: Co sądzisz o używaniu GITa do utrzymywania logów decyzji architektonicznych?

PS: Więcej o ADL i ADR znajdziesz w moim poście: Jak używać ADL i ADR w projekcie?

PS: Zainteresował cię temat? Zajrzyj do mojego newslettera: Model C4.

PS: Jak używać VSCode do tworzenia ADRów? Dowiesz się z mojego posta -> Jak utrzymywać ADL z wykorzystaniem VSCode?

---