Eine große mehrsprachige Laufzeit-Codebasis ändern, ohne bisheriges Verhalten zu brechen

## Den Leitfaden nahe am Code lesen und auf ein übergeordnetes Projekt prüfen Die Anleitungen in einem solchen Projektarchiv sind geschichtet. Ein Leitfaden im Wurzelverzeichnis gibt die grobe Orientierung; Leitfäden in den Unterverzeichnissen tragen Wissen zur jeweiligen Komponente bei, etwa zentrale Klassen, Übersichtstabellen zum Auffinden von Code, örtliche Konventionen und Antimuster. Lies immer den Leitfaden, der dem Code am nächsten liegt, den du gleich anfassen willst – zusätzlich zu dem im Wurzelverzeichnis. - Stelle immer fest, ob das Projektarchiv eigenständig ausgecheckt wurde oder als Komponente in einem größeren übergeordneten Projekt eingebettet ist. Ist es eingebettet, liegt wichtige Dokumentation im Wurzelverzeichnis des übergeordneten Projekts und ist von hier aus nicht sichtbar; lies die dortige Liesmich-Datei, den dortigen Leitfaden und weitere Dokumente der obersten Ebene, bevor du irgendetwas annimmst. - Untersuche und lies frei, aber sammle dieses Wissen, bevor du Änderungen vorschlägst oder vornimmst. - Wenn du dauerhaft gültige, übergeordnete Informationen entdeckst, die in den Leitfäden fehlen, schlage vor, sie dort zu ergänzen, statt sie nur im Gespräch zu belassen. ## Mit den Kurzbefehlen des Projekts bauen und testen, nicht mit eigenen Befehlen Das Projekt hat genau ein maßgebliches Bausystem und darüber eine dünne Schicht aus Kurzbefehlen eines Aufgabenstarters. Nutze für die tägliche Arbeit die Kurzbefehle und greife nur dann auf das darunterliegende Bauwerkzeug zurück, wenn ein Kurzbefehl die benötigte Einstellung nicht anbietet. Erfinde keine eigenen Übersetzungsbefehle. Typische Kurzbefehle, nach denen du suchen und die du wiederverwenden solltest: bauen, alle Tests ausführen, formatieren, die Skriptquellen prüfen, die nativen Quellen prüfen, die Pakete der Systemsprache prüfen, Testausgaben zur Fehlersuche fortlaufend mitlesen, eine einzelne Kompatibilitäts- oder Konformitätssammlung ausführen, einen neuen Test anlegen, Typdefinitionen erzeugen, die Indexdatenbank für den Editor erzeugen, mit dem Werkzeug zur Adressprüfung bauen und testen, einen Abdeckungsbericht erstellen und Quellverzeichnisse überwachen, um bei jeder Änderung einen Befehl erneut auszuführen. ## Das richtige Testziel und seine automatisch erzeugten Varianten finden Mehrere Testfamilien bestehen nebeneinander, und jede hat ihren eigenen Einstiegspunkt: - Konfigurationsgesteuerte Zusammenspieltests: eine serialisierte Konfigurationsdatei, die einen Dienst mit eingebetteten Skriptmodulen, einem Kompatibilitätsdatum, Funktionsschaltern und Anbindungen beschreibt – etwa Dienstanbindungen, strukturierte Daten, Schlüssel-Wert-Speicher und Namensräume für zustandsbehaftete Objekte. - Native Modultests, erzeugt von einem eigenen Makro, mit einem Testkürzel mit Bindestrich im Dateinamen. - Kompatibilitätssammlungen der Laufzeitumgebung und Konformitätssammlungen für Webstandards, jeweils über ihren Namen ausgeführt. - Messläufe zur Leistungsbewertung, über ihren Pfad ausgeführt. Sowohl der Bau- als auch der Testbefehl nehmen ausdrücklich benannte Ziele entgegen und beziehen sich sonst auf den gesamten Baum. Zielnamen tragen zwingend eine Kennzeichnung als Namenszusatz, und die Baumakros erzeugen je Test automatisch mehrere Varianten: eine Standardvariante, die auf die älteste Kompatibilitätsgrundlage festgelegt ist, eine Variante mit dem neuesten Datum und allen aktivierten Schaltern sowie eine Variante mit allen aktivierten vorläufigen Schaltern. Um das richtige Ziel für eine Datei zu finden, lies die Baudatei im selben Verzeichnis oder frage das Bausystem nach allen Zielen in diesem Paket. ## Die wichtigsten Codebereiche kennen und einer ähnlichen Umsetzung folgen Erstelle dir vor dem Bearbeiten eine gedankliche Landkarte, und suche für jede neue Aufgabe eine ähnliche vorhandene Umsetzung und folge deren Muster. - Schnittstellen der Laufzeitumgebung: native Umsetzungen der für Skripte sichtbaren Schnittstellen, dazu die Kompatibilitätsschicht zur Standardbibliothek und deren Tests. - Teilsystem für Ein- und Ausgabe: Speicherung und Zwischenspeicherung zustandsbehafteter Objekte, Nachverfolgung von Anfragen, Ressourcengrenzen, Nebenläufigkeit und der Lebenszyklus der Arbeitsprozesse. Ein Kontextobjekt je Anfrage hält die Anfrage zusammen. - Verbindungsschicht: Anbindung an die Ausführungsmaschine, Typhüllen, Behandlung von Versprechen, Speicherverwaltung und das Modulsystem. - Serverschicht: der Einstiegspunkt des Programms und die Verarbeitung der Konfiguration, mit einem fähigkeitsbasierten Sicherheitsmodell, das eine Schemadatei beschreibt. - Sprachspezifische Bäume für die Kompatibilitätsschicht, eine alternative Skriptlaufzeitumgebung und Bestandteile zur Anbindung der Systemsprache. Kompatibilitätsschichten sind zweigeteilt: die native Hälfte liegt in dem einen Baum, die Skripthälfte in einem anderen, und neue Module müssen in der dafür vorgesehenen Modultabelle eingetragen werden. Typdefinitionen werden aus nativen Typinformationen und handgeschriebenen Deklarationen abgeleitet und stets neu erzeugt, niemals von Hand bearbeitet. ## Dem Hausstil folgen und kleine Commits machen, die alle Tests bestehen Halte dich an den genannten Stilleitfaden des Hauses samt seiner dokumentierten Ausnahmen; wo das Projekt bewusst davon abweicht, ist die Abweichung die Regel. - Übernimm den festgelegten Sprachstandard, die ungewöhnlichen Dateiendungen des Projekts und das Testkürzel mit Bindestrich ganz genau. - Ein einziger Formatierungsbefehl führt sämtliche Formatierer für alle Sprachen aus. Führe ihn und den vollständigen Testbefehl aus, bevor du eine Änderung einreichst. - Eine Prüfung vor dem Commit blockiert Makros für Fehlersuchausgaben im vorgemerkten Code und wiederholt die Formatprüfung. Umgehe sie nicht. - Teile Änderungen in kleine Commits auf; jeder Commit muss für sich allein übersetzbar sein und die Tests bestehen. Hinterlasse keine Nachbesserungs-Commits. - Die Quellen auf Skriptseite sind streng typisiert: die genaue Bedeutung optionaler Eigenschaften, die Schreibweise für private Felder und ausdrückliche Rückgabetypen werden erzwungen. ## Typen der eigenen Basisbibliothek statt der Standardbibliothek verwenden Die Codebasis nutzt für die meisten Typen bewusst ihre eigene Grundbibliothek statt der Standardbibliothek der Sprache. Richte dich nach der umgebenden Datei, statt zu den Standardbehältern zu greifen. Anzuwendende Ersetzungen: eine besitzende Zeichenkette und eine nicht besitzende Zeichenkettensicht statt der Standardzeichenkette; ein Feld fester Größe und ein wachsender Vektor statt des Standardvektors; Besitzzeiger für alleinigen Besitz, für Referenzzählung, für threadsichere Referenzzählung und für schwache Verweise statt der intelligenten Standardzeiger; ein Vielleicht-Typ statt des optionalen Typs; eine Aufrufhülle statt des Standardfunktionsobjekts; eine markierte Vereinigung statt der Variante; ein Feldausschnitt statt roher Bereiche; der Ausnahmetyp der Bibliothek; sowie das Versprechen und das abgezweigte Versprechen der Bibliothek statt der Standardtypen für künftige Ergebnisse. Der Sicherheit halber ist ein Feldausschnitt einem rohen Zeiger vorzuziehen und ein lebensdauergebundener Griff einer nackten Referenz, sobald die Referenz an die Lebensdauer des Eigentümers gebunden ist. Für Fehler nutze das eigens dafür vorgesehene Makro, um einen Vielleicht-Wert auszupacken, die skriptseitigen Anforderungsmakros, wenn der Fehlschlag als Skriptausnahme mit passendem Ausnahmetyp sichtbar werden muss, und die nativen Makros für Zusicherungen und Vorbedingungen für interne Invarianten. ## Verbotene Muster meiden, die Lecks und versteckte Schäden verursachen Diese Regeln gelten ohne Ausnahme; wer sie verletzt, erzeugt schwer erkennbare Datenverfälschungen, Speicherlecks oder Kompatibilitätsbrüche. - Lege niemals maschinenlokale oder maschinenglobale Griffe in Strukturdeklarationen von Werttypen ab; nutze die bereitgestellten Referenzhüllen. - Lege niemals Griffe der Ausführungsmaschine in Versprechenstypen ab, und übergib niemals die Sperre der Maschine an asynchrone Koroutinen. - Halte niemals Verweise aus dem Skriptspeicher auf Objekte der Ein- und Ausgabe ohne die besitzende Hülle; ein Bereichswächter erzwingt das. - Bevorzuge Eigenschaften am Prototyp gegenüber Eigenschaften an der Instanz, denn letztere machen die Optimierung der Speicherbereinigung zunichte. - Friere von Nutzern gelieferte Inhalte niemals tief ein; bei zyklischen Werten ist das unsicher. - Füge einer Schnittstelle, die unbekannte Namen entfernt weiterreicht, niemals Methoden hinzu, ohne sie hinter einem Kompatibilitätsschalter abzusichern, und ändere niemals serialisierte Aufzählungswerte. - Bevorzuge den hinzufügenden Aufruf zur Aufgabenregistrierung gegenüber dem rohen Zugriff auf die Aufgabenliste, und vermeide Wahrheitswerte als Parameter zugunsten starker Wahrheitswerttypen. - Jeder Verweis, der in einem nativen Objekt gespeichert ist, das vom Skriptspeicher aus erreichbar ist, muss den Besuch durch die Speicherbereinigung unterstützen; native Verweiszyklen werden niemals aufgeräumt. Eine eigene Prüfung stellt das sicher. - Fehler durch falsche Nutzung der eingebetteten Datenbank werden immer ausgelöst und niemals unterdrückt; in der Datenbank für zustandsbehaftete Objekte sind Transaktionen untersagt. - Die Auswertung von Modulen darf niemals innerhalb eines Anfragekontexts laufen, und asynchrone Ein- und Ausgabe im globalen Gültigkeitsbereich ist verboten. - Verwende in gemeinsam genutzten Typdeklarationsdateien niemals allgemeine, umgebungsweit sichtbare Typnamen; stelle ihnen immer den Produkt- oder Funktionsnamen voran. Nutze niemals ein bloßes untypisiertes Objekt als Typ; deklariere eine ordentliche Schnittstelle mit bekannten Feldern, die zur Zukunftssicherheit wahlweise einen offenen Datensatz erweitert. - Bearbeite erzeugte Momentaufnahmen niemals von Hand. Behebe die Ursache in der Quellschicht und erzeuge sie neu. ## Verhaltensänderungen hinter Kompatibilitätsschalter oder befristete Schalter setzen Das Projekt gibt eine starke Zusage zur Abwärtskompatibilität: Ist ein Verhalten einmal ausgeliefert, kann es weder entfernt noch stillschweigend geändert werden. Verhaltensänderungen müssen deshalb hinter einem Schalter eingeführt werden, und du wählst den Schalter nach seiner Dauerhaftigkeit. - Datumsgesteuerte Kompatibilitätsschalter gelten je Instanz, sind dauerhaft und in einem Schema definiert, dessen Anmerkungen den Namen des Schalters und das Datum seiner Aktivierung tragen. Jeder Schalter muss dokumentiert sein, bevor sein Aktivierungsdatum eintritt. - Vorläufige Schalter auf Prozessebene werden über die Konfiguration gesteuert und sind für riskante Einführungen mit bedingter Aktivierung gedacht. Sie sind als Aufzählung samt Zuordnungstabelle mit Zeichenketten definiert, und beides muss übereinstimmen. Lege bei nicht standardisierten Schnittstellen strenge Maßstäbe an; setze lieber veröffentlichte Standards um, als projekteigenes Verhalten zu erfinden. ## Mitgelieferte Abhängigkeiten aktualisieren und lokale Patches erhalten Fremdbestandteile werden vom Modulmechanismus des Bausystems in ein externes Verzeichnis mitgeliefert. Die Einbindung steht in der Moduldatei und in einem Bauverzeichnis für Fremdbestandteile; eine überkommene Datei für den Arbeitsbereich gibt es womöglich noch, sie ist aber nicht mehr der maßgebliche Weg. Ziehe bei Fragen zu Kopfdateien und Namensräumen der Grundbibliothek deren mitgelieferte Quellen unmittelbar heran, statt zu raten. Für mehrere Fremdbestandteile werden örtlich gepflegte Korrektursätze vorgehalten, die beim Bauen angewendet werden. Diese Korrekturen bringen projekteigene Anpassungen und neue Schnittstellen ein; prüfe und aktualisiere sie daher bei jeder Anhebung des betreffenden Bestandteils. Beachte außerdem, dass das Projekt eine alternative Speicherverwaltung nutzt, deren Verhalten von der Voreinstellung abweicht; jede Untersuchung des Speicherverhaltens muss das berücksichtigen. Bei einer größeren Anhebung der Ausführungsmaschine oder eines Fremdbestandteils gilt: Frage vor dem Beginn nach der genauen Zielversion und danach, welche Korrekturen oder Anpassungen erhalten bleiben müssen, und folge dann den dokumentierten Schritten zum Abgleichen, Anwenden der Korrekturen, Umbasieren, Neuerzeugen der Korrekturen und Anheben der Versionsnummer. Konflikte beim Zusammenführen sind häufig und brauchen fast immer menschliches Urteilsvermögen, damit die projekteigenen Änderungen erhalten bleiben; löse sie niemals automatisch ohne menschliche Prüfung. Vergewissere dich, dass die vollständige Testsammlung besteht, und weise auf jeden neu aufgetretenen Hinweis auf veraltete Bestandteile hin. ## Verteilte Dokumentation finden und Korrekturen vorschlagen, wenn sie falsch ist Die Dokumentation ist verteilt, nicht an einer Stelle gebündelt. Ein Dokumentenverzeichnis behandelt übergreifende Themen wie das Einrichten der Arbeitsumgebung, Richtlinien zum Hinzufügen neuer Schnittstellen und Verfahren zur Anhebung von Fremdbestandteilen, während einzelne Quellverzeichnisse oft eine eigene Liesmich-Datei oder einen eigenen Leitfaden mit tiefen Einzelheiten zum Teilsystem enthalten. Suche von dir aus danach, wenn du in einem unbekannten Bereich arbeitest, bevor du rätst oder nachfragst. Wenn Dokumentation fehlt, ungenau oder veraltet ist, schlage eine Aktualisierung vor, statt zu schweigen. Prüfe zuerst die Fakten, und übertrage Änderungen an der Dokumentation nicht, ohne ihre Richtigkeit mit einer betreuenden Person abzustimmen.