ADR 0003

ADR 0003: Die App legt ihre Log-Kategorien selbst fest

← ADR 0002	ADR-Verzeichnis	ADR 0004 →

Status: angenommen
Herkunft: #68 (Befund und Entscheidung)

Kontext

Bis Version 2 war LogCategory ein Enum mit neun fest eingebauten Fällen (.appState, .debug, .general, .manager, .service, .storage, .uncategorized, .user, .view) und .custom(_ name: String) für alles andere. Die Fälle waren der Wortschatz, den der Betreuer in seinen eigenen Apps benutzt. Das Paket selbst brauchte davon nur .uncategorized als Standardwert des Parameters category:. Eine App mit eigenen Kategorien hatte zwei Schreibweisen nebeneinander, .storage und .custom("To Do"). Für die Log-Level hatte ADR 0002 kurz vorher entschieden, dass die App ihre Stufen selbst festlegt.

Entscheidung

• Das Paket liefert keine Log-Kategorien bis auf .uncategorized. LogCategory ist eine Struktur mit einem Namen und einem öffentlichen Initialisierer init(_ name: String).
• Die App legt ihre Kategorien als Erweiterung von LogCategory selbst an.
• .custom(_:) entfällt ohne Übergangsphase.
• .uncategorized bleibt die eine Kategorie im Paket. Sie steht für „keine Kategorie“, hat einen leeren Namen und ist weiter der Standardwert von category:.
• Zwei Kategorien sind gleich, wenn ihre Namen gleich sind. LogCategory ist Sendable und Hashable.
• README und Demo-App zeigen die Kategorien aus Version 2 als Vorschlag.

Begründung

Welche Kategorien eine App braucht, hängt von der App ab. Die neun Namen des Betreuers sind für eine fremde App zufällig. Wenn die App alle Kategorien selbst festlegt, gibt es nur eine Schreibweise statt zwei. Das passt zu ADR 0001 und ADR 0002: Targets, Log-Funktionen und Stufen legt die App ebenfalls selbst an. Version 3 bricht ohnehin, deshalb kostet die Änderung jetzt am wenigsten.

.uncategorized bleibt, weil es keine Benennung ist, sondern das Fehlen einer Kategorie. Ohne einen solchen Wert müsste category: entweder Pflicht werden oder optional, und dann müsste jeder Target mit nil umgehen.

Konsequenzen

• Breaking Change für jede App, die eine eingebaute Kategorie oder .custom(_:) benutzt. Sie braucht einen Block mit ihren Kategorien.
• Ein switch über die Kategorie braucht einen default-Zweig, weil Kategorien Werte und keine Enum-Fälle sind. Für eine einzelne Prüfung reicht ==.
• Zwei Kategorien mit gleichem Namen sind dieselbe Kategorie, auch wenn die App sie an zwei Stellen definiert.

Verworfene Alternativen

• Die eingebauten Kategorien behalten. Kategorien haben keine Rangfolge, und kein Target musste zwei Namen für dasselbe behandeln wie bei den Stufen. Verworfen, weil das Paket damit weiter einen fremden Wortschatz vorgibt und es zwei Schreibweisen gibt.
• category: LogCategory? = nil statt .uncategorized. Bildet „keine Kategorie“ genauer ab. Verworfen, weil jeder Target nil behandeln müsste und sich die Signatur von LogTarget dafür noch einmal ändern würde.
• category: ohne Standardwert. Verworfen, weil dann jeder Aufruf eine Kategorie nennen müsste, auch dort, wo keine passt.