Eine plattformübergreifende UI-Bibliothek pflegen, ohne ihre Paketschichten zu brechen

## Festlegen, in welche Paketschicht jedes Stück Code gehört Ordne die Codebasis als kleinen Stapel von Schichten mit je einer Verantwortung: reaktive Grundbausteine, die Framework-Hooks als anzeigefreie Ressourcen ausführen; eine Bindungsschicht, die diese Grundbausteine an das Zustandssystem des Frameworks anschließt; eine vom Framework unabhängige Kernlaufzeit, der die Fachlogik gehört; und je ein Auslieferungspaket pro Zielplattform (Web, nativ, Terminal), das den Kern erneut exportiert und plattformspezifische Oberflächenbausteine ergänzt. Ein privater Komponentenbaukasten enthält die maßgebliche Oberflächenquelle, die in die Projekte der Nutzenden kopiert und nicht als Laufzeitabhängigkeit veröffentlicht wird. Gemeinsam genutztes Bauwerkzeug liegt in einem eigenen internen Paket. Regeln für die Einordnung: - Vom Framework unabhängige Logik gehört in das Kernpaket. An eine Plattform gebundene Laufzeiten gehören in die Auslieferungspakete. - Die an das Framework gebundene Laufzeit liegt in einem Unterpfad des Kernpakets, den jedes Auslieferungspaket erneut exportiert, sodass es eine Umsetzung gibt statt einer Kopie je Plattform. - Nutzende installieren das Kernpaket niemals direkt; sie installieren genau ein Auslieferungspaket. - Integrationspakete, die einen externen Anbieter auf die Kernlaufzeit abbilden, bilden eine eigene Schicht und spalten die Kernlogik niemals ab. ## Öffentliche Exporte nur ergänzen, veröffentlichte nie entfernen Die öffentliche Schnittstelle jedes veröffentlichten Pakets ist ausschließlich erweiterbar. Zieht ein Symbol um, wird sein Export auf die neue Datei umgebogen; ein bereits ausgelieferter Export wird niemals gelöscht. Eine Prüfung innerhalb des Repositorys kann nachgelagerte Nutzende nicht sehen, deshalb ist selbst das Entfernen eines scheinbar ungenutzten Typs eine brechende Änderung. Eine echte Verhaltensänderung wird als eigene, bewusste Änderung ausgeliefert und niemals in einer Verschiebung oder Umbenennung eingeschmuggelt. Ersetzt eine lange Umstellung eine alte Umsetzung durch eine neue Architektur, exportiert der Einstiegspunkt des Pakets für diese Zeit beide Pfade erneut und bleibt trotzdem ausschließlich erweiterbar. Während einer solchen Umstellung gilt: - Neues Verhalten kommt auf die maßgebliche Schnittstelle, niemals auf den überholten Pfad. - Der gemeinsame Kernbaustein wird wiederverwendet, statt ihn je Integration nachzubauen. - Wiederverwendung geht vor der Einführung eines weiteren Abwahlschalters. ## Einen Provider-Adapter mit der Standard-Dateistruktur bauen Ein Integrationsadapter bildet einen externen Anbieter über einen Einstiegs-Hook, eine Reihe von Zugriffs-Hooks und reine Umwandler auf die Kernlaufzeit ab. Die leitende Faustregel: Die Laufzeitdatei orchestriert, reine Module wandeln um, der Steuerbaustein reduziert, sofern es einen gibt, und Hooks lesen nur. - Wahl der Kernlaufzeit. Baue entweder auf der Laufzeit mit externem Speicher auf, wenn die Nachrichten aus einer Quelle abgeleitet werden, die dem Anbieter gehört, oder auf der lokalen Laufzeit samt Adapter für das Chatmodell, wenn der Anbieter keinen Zustand der Gesprächsstränge hält. Umhülle beides mit der gemeinsamen Laufzeit für mehrere Gesprächsstränge, sobald Listen von Gesprächssträngen gebraucht werden. Verwende die ausgelieferten Laufzeitkerne wieder; baue keinen parallelen Zustandshalter für die Laufzeit der Gesprächsstränge von Hand. - Offenlegung des Zustands. Gib den Laufzeitzustand über die gemeinsame Fabrik für Laufzeitzusätze an die Zugriffs-Hooks weiter, nicht über eine von Hand gebaute Kennzeichnung mit eindeutigem Symbol samt Prüffunktion. - Fester Dateisatz. Eine ausschließlich orchestrierende Einstiegsdatei der Laufzeit, eine Instanz der Laufzeitzusätze, eine Datei mit Zugriffs- und Aktions-Hooks, eine reine Datei zur Umwandlung von Nachrichten in beide Richtungen und eine Datei mit den Typen. Ergänze einen Steuerbaustein für Gesprächsstränge samt reinem Zustandsreduzierer, wenn der Adapter deren Zustand besitzt, sowie einen getrennten Einstieg im Server- oder Node-Unterpfad, wenn das Protokoll das Übertragungsformat bestimmt. - Ausschließlich serverseitiger Code. Halte ausschließlich serverseitigen Code und den Code des Entwicklungsbaukastens des Anbieters im Server- oder Node-Unterpfad, außerhalb des Standardeinstiegs und außerhalb des nativen Einstiegs. - Tests. Lege sie neben jedes Modul und decke damit den Umwandler in beide Richtungen, den Reduzierer oder Steuerbaustein und jeden Zugriffs-Hook ab. Vom Anbieter getriebene Entscheidungen bleiben beweglich: auf welchem Kernbaustein aufgebaut wird, dünne Hülle gegenüber Sammler gegenüber Steuerbaustein, eigene Übertragungswege, wie umfangreich die Einbindung menschlicher Entscheidungen ausfällt und wie tief die Unterstützung für Listen von Gesprächssträngen reicht. ## Adaptern gleiche Funktionen und absturzfreie Konverter geben Gleichstand über die Laufzeiten hinweg. Halte die Fähigkeiten über alle Adapter hinweg auf gleichem Stand. Landet eine Fähigkeit auf einer Laufzeit, wird sie auf jeder Laufzeit angeboten, auf die das Konzept zutrifft, oder es wird schriftlich festgehalten, warum eine davon abweicht. Eine stillschweigende Lücke im Gleichstand wird für alle, die den Adapter wechseln, zu einer brechenden Erwartung. Abwehrende Umwandler. Umwandler und Darstellungsbausteine für Inhaltsblöcke dürfen bei nicht gesetzten Feldern, fehlenden Feldern oder nicht verfügbaren Fähigkeiten der Plattform niemals einen Fehler werfen. Wehre Anbieterdaten ab, die von der Spezifikation abweichen, und halte Schnittstellen, die es nur im Browser gibt, aus Codepfaden heraus, die auch auf einem Server, in einer Terminaldarstellung oder auf einem nativen Ziel laufen. Muster, die niemals eingeführt werden dürfen: - Ein paralleler Zustandshalter für die Laufzeit der Gesprächsstränge, der die ausgelieferten Laufzeitkerne verdoppelt. - Ein Behelf aus Änderungsbenachrichtigung und Versionszähler, um nicht reaktiven Zustand in den Komponentenbaum zu überführen und ein Neuzeichnen auszulösen. - Das Anflanschen von Methoden an Objekte über die Erzeugung von Prototypen. - Das nachträgliche Verbiegen von Objekten, die der aufrufenden Seite gehören. ## Mit dem gemeinsamen Build-Tool bauen und Release-Notes ergänzen Jedes veröffentlichungsfähige Paket wird mit dem gemeinsamen Bauwerkzeug gebaut. Füge keine eigene Baukonfiguration je Paket hinzu und greife nicht direkt zu einem anderen Bündelwerkzeug oder zur Kommandozeile des Compilers. Die Exportzuordnungen sind ausschließlich modulbasiert und stellen die Typen voran: Die Typdeklarationen stehen vor der Standardbedingung, und die Pakete erklären sich als frei von Nebenwirkungen. - Ein maßgebliches Verzeichnis für die Oberflächenquelle. Vorlagen und Beispiele verweisen über die Pfadzuordnungen des Compilers darauf und führen keine bytegleichen Doppel mit, außer dort, wo ein minimaler Starter bewusst eine eigene Kopie ausliefert. Ein Abgleichsskript hält diese Kopie bytegleich, und jede beabsichtigte Abweichung wird in der Ausnahmeliste des Skripts eingetragen. - Die Konventionen für den Verzeichnisaufbau unterscheiden sich nach Absicht: parallele Verzeichnisse, wenn jeder Baustein in beiden Ausprägungen vorliegt, und vereinzelte Namenszusätze für Varianten, wenn nur einige Dateien eine zweite Ausprägung haben, wobei die Datei ohne Zusatz die Standardquelle ist. - Führe die Prüfaufgabe für die Erweiterungen des Compilers erneut aus, wenn die Werkzeugkette des Compilers oder deren Erweiterungen angehoben werden. Ein grüner Bau allein belegt nicht, dass die Werkzeugkette noch unversehrt ist. - Jedes Paket, das vom veröffentlichten Bündel zur Laufzeit eingebunden wird, gehört in die Laufzeitabhängigkeiten und nicht in die Entwicklungsabhängigkeiten, damit das Bündelwerkzeug es als extern behandelt. Falsch einsortiert wird das Paket eingebettet und schleppt unauflösbare weiterführende Einbindungen in die Bauvorgänge der Nutzenden. - Ein zum Kopieren installierbarer Komponenteneinstieg muss in sich geschlossen sein: Führe jede interne Einbindung von Komponenten und jede Einbindung von Formatvorlagen als Abhängigkeit im Verzeichnis auf, damit der Installierer niemals eine Datei mit einer unauflösbaren Einbindung ablegt. - Jede Änderung an einem veröffentlichten Paket bringt einen Eintrag in den Freigabehinweisen mit. Erhöhe die Version immer nur an der letzten Stelle; Erhöhungen an der mittleren oder ersten Stelle brauchen die Zustimmung der Betreuenden. Private Pakete sind ausgenommen. ## Die generierte API-Referenz nicht von Hand bearbeiten Der gesamte erzeugte Baum der Schnittstellenreferenz gehört seinem Erzeugungsskript und wird nicht von Hand gepflegt. - Seiten mit der Kennzeichnung für vollständig erzeugte Seiten gehören ganz dem Erzeuger. Änderungen von Hand innerhalb eines erzeugten Blocks werden beim nächsten Lauf vernichtet; dauerhafter Fließtext gehört stattdessen in die Kommentare der Quelle. - Von Hand geschriebene Inhalte, die eine Neuerzeugung überstehen müssen, stehen ausschließlich in den dafür vorgesehenen Feldern für Handarbeit oder Beispiele. - Eine vollständig von Hand gepflegte Seite muss die Kennzeichnung zum Überspringen der automatischen Erzeugung unmittelbar nach ihrem Kopfbereich tragen. Diese Kennzeichnung hält die Seite in der Navigation des Abschnitts und nimmt sie vom Aufräumen aus; ohne sie wird eine unerwartete, nicht erzeugte Seite als ungepflegt und veraltet gemeldet, und der strenge Modus schlägt fehl. - Auch die Beschreibungsdateien für die Navigation des Abschnitts und der Wurzel unterhalb dieses Baums werden erzeugt. Bearbeite sie niemals von Hand. - Die fortlaufende Integration erzeugt im strengen Modus neu und schlägt bei jeder Abweichung fehl; erzeuge deshalb lokal neu, bevor du einreichst. ## Stil dem Linter und Formatter überlassen und kaum Kommentare schreiben Führe das Prüfwerkzeug des Repositorys aus, für mechanische Mängel auch dessen Modus zur automatischen Behebung. Die Formatierung gehört dem Formatierwerkzeug; formatiere niemals von Hand und bringe in der Prüfung niemals Kleinigkeiten zu Abständen oder Formatierung vor. Weil reaktive Ressourcen auf Framework-Hooks aufbauen, werden die Regeln zu Abhängigkeitslisten und Aufrufreihenfolge der Hooks von den eigenen Hook-Regeln des Prüfwerkzeugs durchgesetzt. Damit diese Regeln einen Funktionsrumpf analysieren können, muss die Funktion so benannt sein, dass die Werkzeuge des Frameworks sie als Hook erkennen: Ziehe eine Ressource in eine Funktion mit dem üblichen Namensvorsatz für Hooks heraus und übergib diese der Fabrik für Ressourcen; und gib den Hilfsfunktionen zum Erzeugen der Wurzel einen benannten Funktionsausdruck statt einer Pfeilfunktion. Der Standard sind null Kommentare im Code. Lösche jeden Kommentar, der den Code wiederholt, seine Geschichte festhält oder auf den aktuellen Änderungsantrag zeigt. Behalte einen Kommentar nur, wenn er einen Grund festhält, den keine spätere lesende Person aus dem Code selbst wiedergewinnen kann, etwa eine verborgene Invariante, eine nicht offensichtliche Einschränkung oder einen Behelf für ein vorgelagertes Projekt, und schreibe ihn als sachlichen Aussagesatz. ## Tests neben jedes Modul legen und keine Snapshots verwenden Tests liegen neben dem geprüften Modul und binden es über einen relativen Pfad ein, niemals über den Paketnamen, damit ein Test stets die lokale Quelle ausführt und nicht ein aufgelöstes Bauergebnis. - Decke den Umwandler in beide Richtungen, den Reduzierer oder Steuerbaustein und jeden Zugriffs-Hook in einer eigenen Testdatei ab. - Baue Attrappen mit der Hilfsfunktion des Testläufers für vorgezogene Attrappen und übernimm dabei stets das ursprüngliche Modul in die Attrappe, damit unangetastete Exporte ihr echtes Verhalten behalten. - Verwende keine Zusicherungen über Momentaufnahmen; prüfe die konkreten Werte, auf die es ankommt, damit ein Fehlschlag den tatsächlichen Rückschritt benennt. ## Änderungen mit nur einem Zweck, Beschreibung und Reproduktion einreichen - Ein Anliegen je Änderungsantrag. Zerlege eine große oder mehrzweckige Änderung in getrennte Einreichungen, damit jede klein genug zum Prüfen ist, für sich bewertet werden kann und sich sauber zurücknehmen lässt, wenn sie etwas verschlechtert. - Schreibe eine echte Beschreibung, keinen erzeugten Platzhalter. Halte fest, was die Änderung ist, warum sie nötig ist und wie sie umgesetzt wurde, damit die prüfende Person genug Zusammenhang hat, ohne den Unterschied rückwärts entschlüsseln zu müssen. Der Titel benennt die Änderung in einer Zeile; Abwägungen und Abweichungen gehören in den Rumpf. - Begründe jede Abweichung von der bestehenden Praxis des Repositorys. Löst die Codebasis ein Problem bereits auf eine bestimmte Weise, folge ihr; jemand hat diesen Weg bewusst gewählt, also braucht ein anderer einen schriftlichen Grund statt einer persönlichen Vorliebe. - Halte unzusammenhängende Änderungen aus dem Unterschied heraus. Nebenbei erledigte Löschungen, Umbauten, Neuformatierungen und Ergänzungen nach dem Motto „wenn ich schon einmal hier bin" verschütten die eigentliche Änderung und verlangsamen die Prüfung. Eröffne eine getrennte Einreichung oder ein Ticket, wenn es nur darum geht, auf etwas hinzuweisen. - Eröffne ein Ticket, bevor du eine nicht triviale Funktionsänderung angehst. Ein Absatz genügt, damit die Betreuenden bestätigen, dass die Richtung erwünscht ist, bevor viel Zeit hineinfließt. Triviale Korrekturen wie Tippfehler oder kleine Änderungen an der Dokumentation brauchen kein Ticket. - Lege eine minimale Nachstellung bei. Jede Fehlermeldung und jede Korrektur braucht eine lauffähige Nachstellung auf genau der betroffenen Version. Können die Betreuenden das gemeldete Verhalten nicht nachstellen, wird die Meldung geschlossen. - Bestätige, dass die Korrektur die eigentliche Ursache trifft. Weise nach, dass der gemeldete Fehlschlag mit der Änderung verschwindet und ohne sie zurückkehrt, und erkläre den Wirkzusammenhang. Eine Änderung, die das Symptom durch das Austauschen eines Werts, das Streichen einer Funktion oder das Aufweiten eines Typs verdeckt, wird abgelehnt. - Halte Dokumentation und erzeugte Referenz im Gleichschritt mit dem Code in derselben Einreichung. Erzeuge die Referenz neu und aktualisiere jede Seite, deren Aussagen die Änderung ungültig macht. Die Automatisierung soll bei Abweichungen in der Dokumentation fehlschlagen, statt eine Schnittstelle stillschweigend verschwinden zu lassen oder ihre Pflege auf eine spätere Änderung zu verschieben. ## Änderungen vermeiden, die im Review abgelehnt werden, etwa nachgebaute Framework-Funktionen - Neu erfinden, was das Framework bereits mitbringt. Baue auf den gemeinsamen Grundbausteinen auf, statt Laufzeitzustand, Reaktivität oder andere Verdrahtung nachzubauen; ein paralleler Mechanismus driftet vom Rest der Codebasis weg und kostet alle Pflegeaufwand. - Leichtfertig schwergewichtige oder nicht quelloffene Abhängigkeiten hinzufügen. Kommerziell lizenzierte Bibliotheken sind in einem quelloffenen Projekt tabu, und schwergewichtige Abhängigkeiten oder neue Bauschritte betreffen alle Beitragenden; sie brauchen daher eine Begründung und die Freigabe der Betreuenden. - Eine neue Beispielanwendung ausliefern, die eine bestehende verdoppelt. Sieh zuerst die vorhandenen Beispiele durch; deckt eines die Integration bereits ab, gewinnt eine Beinahe-Kopie nichts und gehört in ein eigenes persönliches Repository, sofern die Betreuenden nicht darum gebeten haben. - Einen Fehler durch eine Verschlechterung der Bedienerfahrung beheben. Eine Funktion abzuschalten, eine Bewegung wegzulassen oder eine Schnittstelle aufzuweiten, um einen Darstellungs- oder Zitterfehler zu verdecken, ist keine annehmbare Korrektur, selbst wenn die ursprüngliche Meldung zutrifft. - Abwehrende Prüfungen hinzufügen, die die Werkzeugkette bereits erzwingt. Unter den strengsten Einstellungen des Compilers einschließlich der genauen Prüfung optionaler Eigenschaften sind Absicherungen gegen fehlende Werte und optionale Eigenschaften überflüssig. - Verpflichtende Prüfungen überstimmen, um zusammenzuführen. Erzwinge eine Zusammenführung erst, wenn die Liste der Prüfungen in jeder Zeile bestanden oder ausdrücklich übersprungen zeigt; filtere die bestandenen und übersprungenen Zeilen heraus und stelle sicher, dass nichts übrig bleibt, denn eine abgeschnittene Liste hat schon einmal eine fehlgeschlagene Prüfung verborgen. Ist eine für das Repository eigene Prüfung fehlgeschlagen oder ausstehend, löse sie auf, statt sie zu überstimmen. ## Änderungen anderer Agenten im selben Arbeitsbaum nicht überschreiben Gehe davon aus, dass andere automatisierte Agenten und Menschen gleichzeitig denselben Arbeitsbaum bearbeiten. Sieh dir vor jeder Bearbeitung den aktuellen Stand des Arbeitsbaums an und überschreibe keine Änderungen, die nicht von dir stammen. Halte jede Änderung eng umrissen, damit sich gleichzeitige Arbeiten sauber trennen lassen. Achte den Ablauf der Versionsverwaltung des Projekts, statt anzunehmen, dass rohe Befehle der Versionsverwaltung angebracht sind. Deutet der Arbeitszweig darauf hin, dass das Projekt über ein Werkzeug gesteuert wird, das über der Versionsverwaltung liegt, dann lege keine Zweige an, nimm keine Dateien auf, erstelle keine Einträge und schreibe die Historie nicht mit direkten Befehlen um, sofern nicht ausdrücklich darum gebeten wird.