Lasst uns `ARCHITECTURE.md` hinzufügen

• Ein Beitrag mit dem Vorschlag, im Repo eine Datei hinzuzufügen, die die Architektur des Projekts erklärt, um die Beteiligung an Open Source zu erleichtern

• Der größte Unterschied zwischen Personen, die nur gelegentlich zu einem Projekt beitragen, und den Kernentwicklern ist das Verständnis der Architektur des Projekts

• Wenn man mit der Struktur nicht vertraut ist, dauert das Schreiben eines Patches zwar mehr als doppelt so lang, aber noch viel mehr Zeit – mehr als das Zehnfache – geht dafür drauf, herauszufinden, wo überhaupt etwas geändert werden muss

• Eine Datei wie ARCHITECTURE.md schreiben, die die Architektur auf hoher Ebene beschreibt

→ Kurz halten, damit sie jede*r lesen kann, und nur die Teile festhalten, die sich nicht oft ändern

→ Nicht versuchen, sie mit dem Code zu synchronisieren, sondern etwa zweimal im Jahr erneut durchsehen

So schreibt man den Inhalt

• Mit einem Überblick aus der Vogelperspektive über das Problem beginnen, das gelöst werden soll

• Eine etwas detailliertere Code-Map: „Wo befindet sich das, was X macht?“

• Die groben Module und ihre Beziehungen beschreiben: Was jedes Modul tut, sollte auf andere Dokumente verweisen

• Die Namen wichtiger Dateien, Module und Typen aufführen

→ Damit Leser danach per Namen suchen können; nicht direkt verlinken (weil Links kaputtgehen können)

• Die Grenzen zwischen Layern und Systemen klar angeben

• Gute Beispiele

• Rust Analyzer Architecture.md - https://github.com/rust-analyzer/rust-analyzer/…

• Caddy Architecture : https://caddyserver.com/docs/architecture

[xguru]

Und es ist auch ein guter Vorschlag, im Haupt-README.md nach Möglichkeit Erklärungen zu den einzelnen Ordnern des Projekts aufzunehmen.

• https://news.ycombinator.com/item?id=26050082

Beispiel: https://github.com/diem/diem/…

Wenn möglich, sollte man für jeden Ordner eine Beschreibung hinzufügen, und es wäre schön, wenn GitHub den Inhalt eines README in einem Ordner auch auf der übergeordneten Ebene anzeigen würde.

In diesem Zusammenhang solltet ihr euch auch Architecture Decision Records ansehen.

• Warum man ADRs schreiben sollte: https://de.news.hada.io/topic?id=2665