Home

PrettyLog

Dieses Wiki hält die Architekturentscheidungen von PrettyLog. Es beschreibt ausschließlich den heute gültigen Zustand. Was hier steht, gilt; was nicht mehr gilt, ist als abgelöst gekennzeichnet und wird nicht gelöscht.

Das Verzeichnis aller Entscheidungen steht unter ADR-Verzeichnis.

Was hierher gehört und was nicht

Die Trennlinie verläuft zwischen Vorgang und Zustand: Was einen Abschluss hat, bleibt ein Issue; was keinen hat, steht hier.

	Ort
Architekturentscheidungen und ihr Verzeichnis	dieses Wiki
Tasks, Recherche-Aufträge, Entscheidungs-Tickets, Specs, Wayfinder-Maps	Issue
Begriffsglossar	nur lokal, neben dem Code, nicht versioniert
Recherche-Befunde	als Auflösungs-Kommentar am jeweiligen Recherche-Ticket

Warum Recherche-Befunde nicht hierher gehören. Ein Befund ist eine Momentaufnahme mit Datum: Er sagt, wie die Welt zum Zeitpunkt der Erhebung aussah. Eine Wiki-Seite behauptet Gegenwart und müsste gepflegt werden, sonst lügt sie. Der Nachschlagewert eines Befundes entsteht ohnehin über die ADR, die ihn zitiert und verantwortet, und zwar über das Feld Herkunft.

Eine neue ADR anlegen

1. Nächste freie Nummer nehmen, Datei ADR-NNNN.md im Wurzelverzeichnis des Wikis anlegen. Keine Unterordner: Der Namensraum ist flach, ein Ordner verschwindet aus Name und URL, und [[Ordner/Seite]] löst nicht auf.

2. Diesen Aufbau verwenden:

   # ADR NNNN: <Titel>
   
   <div align="center">
   
   | [← ADR MMMM](…/wiki/ADR-MMMM) | [ADR-Verzeichnis](…/wiki/ADR-Verzeichnis) | [ADR OOOO →](…/wiki/ADR-OOOO) |
   | :-- | :-: | --: |
   
   </div>
   
   **Status:** angenommen<br>
   **Herkunft:** [#5](…) (Research), [#7](…) (erste Fassung)
   
   ## Kontext
   ## Entscheidung
   ## Begründung
   ## Konsequenzen
   

   ## Verworfene Alternativen ist ein anerkannter optionaler fünfter Abschnitt. Sonst wird von diesem Aufbau nicht abgewichen. Der Status kennt zwei Werte, angenommen und abgelöst durch ADR NNNN, Zusätze in Klammern.

   Das <br> hinter dem Status ist nicht schmückend, sondern nötig. Markdown zieht einen einfachen Zeilenwechsel zusammen; ohne den harten Umbruch stünden Status und Herkunft gerendert hintereinander. Zwei Leerzeichen am Zeilenende täten dasselbe, überleben aber kein Trimmen.

   Die Navigation steht im <div align="center">, und die Leerzeilen darin sind Pflicht. Ohne sie liest Markdown die Tabelle nicht als Tabelle. Volle Breite ist nicht möglich: GitHub bemisst Tabellen an ihrem Inhalt (width: max-content, gedeckelt durch max-width: 100%), und diese Regel schlägt das Attribut width="100%". Überschreiben ließe sie sich nur mit style, und das entfernt der Sanitizer, dessen Positivliste align und width führt, aber weder style noch class noch id.

3. Die Navigation der Vorgängerseite zeigt schon auf die neue Seite. Jede ADR verlinkt ungeprüft auf die nächste Nummer, auch wenn es sie noch nicht gibt. Sobald du die Seite anlegst, funktioniert der Pfeil von selbst. Nur ADR 0001 hat keinen Rückwärtspfeil, weil ADR 0000 nie existieren wird.

4. Eine Zeile ins ADR-Verzeichnis eintragen. Das Verzeichnis wird von Hand gepflegt.

5. Klon pushen, am selben Tag.

Die Nummer ist die dauerhafte Kennung, der Titel nicht. Deshalb steht im Dateinamen nur die Nummer und der sprechende Titel als Überschrift in der Seite: Eine Umbenennung bricht dann keinen einzigen Link.

Eine ADR zeigt nur ihren heute gültigen Stand. Ändert sich eine Festlegung, wird die ADR auf den neuen Stand umgeschrieben, ohne Vermerk, was vorher galt. Die früheren Fassungen stehen in der Git-Historie des Wikis. Deshalb nennt die Commit-Nachricht, was sich geändert hat und warum, und das Herkunftsticket kommt ins Feld Herkunft. Eine ganz abgelöste ADR behält ihre Seite, bekommt den entsprechenden Status und wird nie gelöscht.

Wie verwiesen wird

Richtung	Form
von hier auf eine andere Seite	[[ADR 0014]]
von hier nach draußen	volle URL als Markdown-Link, Kurzform als Anzeigetext: [#75](https://github.com/bennokress/PrettyLog/issues/75)
von einem Issue hierher	volle URL
aus dem Code hierher	gar nicht, der Code nennt nur die Kennung im Klartext
von hier auf das Glossar	gar nicht, es liegt nicht im Repository

Auf das Begriffsglossar wird nie verwiesen. Es ist gitignoriert und liegt nur auf dem Rechner des Betreuers, ein Link darauf wäre für jeden anderen eine Sackgasse. Eine ADR benutzt die vereinbarten Begriffe einfach, und wo eine Definition gebraucht wird, steht sie ausgeschrieben in der ADR.

Nackte Verweise funktionieren hier nicht. GitHub verlinkt in Wikis weder #75 noch GH-75 noch eine nackte URL. Jeder Verweis nach draußen muss als vollständiger Markdown-Link ausgeschrieben werden, sonst steht dort nur Text.

Ein toter [[…]]-Verweis wird nicht gemeldet. Er ist am Aussehen erkennbar, aber nichts prüft ihn automatisch. Wer eine Seite umbenennt, bricht Links ohne jede Rückmeldung.

Zwei Eigenheiten des Werkzeugs

Bindestrich und Leerzeichen sind dasselbe. ADR-0014 und ADR 0014 führen zur selben Seite. Zwei Dateien, die sich nur darin unterscheiden, kollidieren still: Beide erscheinen in der Seitenliste, erreichbar ist nur eine, und es gibt dafür keine Warnung.

Der Branch heißt master und bleibt es. Wiki-Repositories wurden von der Umstellung auf main ausgenommen. Wer umbenennt, bekommt ein Wiki, das nichts mehr anzeigt.