Eine gemeinsame Bibliothek oder ein SDK ändern, ohne die öffentliche API zu brechen

## Vor der Fertigmeldung alle Tests und Builds ausführen Führe die vollständige Prüfkette des Projekts aus, bevor du eine Änderung als abgeschlossen meldest, wenn diese Änderung Laufzeitcode, Tests oder das Build-/Testverhalten betrifft. Die Prüfung gilt, wenn du Folgendes änderst: - Kernbibliothekscode oder gemeinsam genutzte Hilfsprogramme. - Tests, einschließlich Snapshot-Tests. - Beispielprojekte. - Build- oder Testkonfiguration (Abhängigkeitsverzeichnisse, Aufgabenläufer-Dateien, Konfiguration für den Dokumentationsaufbau, CI-Arbeitsabläufe). Bei Änderungen, die nur die Dokumentation oder Repository-Metadaten betreffen (Dokumentation, Leitfäden für Mitwirkende, Metadatendateien), kannst du die vollständige Prüfung überspringen, es sei denn, der Nutzer verlangt ausdrücklich die vollständige Prüfkette. Entscheide anhand der tatsächlich geänderten Dateien, ob eine Prüfung nötig ist – nicht anhand eines subjektiven Eindrucks vom Umfang der Änderung. Führe nach jeder Korrektur die gesamte Prüfkette erneut aus – ein Teildurchlauf verbirgt Rückschritte, die durch die Korrektur selbst entstanden sind. Wenn du eine Anbindung an die Programmierschnittstelle einer externen Plattform vornimmst, ziehe die maßgebliche Dokumentation dieser Plattform heran, statt dich auf allgemeine Annahmen zu Programmierschnittstellen zu verlassen, und untersuche den lokalen Codepfad für das eigene Verhalten der Bibliothek. ## Git-Zweig oder Arbeitsverzeichnis nur mit Erlaubnis des Nutzers wechseln Arbeite standardmäßig im aktuellen Checkout des Nutzers und auf dem aktuellen Zweig. Läuft die Aufgabe bereits innerhalb eines ausgewählten Arbeitsverzeichnisses, nutze dieses Arbeitsverzeichnis, ohne zusätzlich um Erlaubnis zu bitten. Erstelle kein weiteres Arbeitsverzeichnis und wechsle nicht dorthin, und erstelle oder wechsle keine Zweige, es sei denn, der Nutzer verlangt oder genehmigt genau diese Aktion ausdrücklich im laufenden Gespräch. Eine Bitte, Änderungen umzusetzen, zu untersuchen, zu überprüfen, zu testen oder zu verifizieren, berechtigt für sich genommen nicht dazu, das aktive Arbeitsverzeichnis oder den aktiven Zweig zu wechseln. Ist eine Isolierung oder ein anderes Checkout tatsächlich nötig, erkläre den Grund und frage nach, bevor du den Git-Zustand änderst. Das gilt auch dann, wenn eine andere Regel oder ein anderer Arbeitsablauf ein verknüpftes Arbeitsverzeichnis empfiehlt: Halte inne und bitte um Genehmigung, statt automatisch eines auszuwählen oder zu erstellen. ## Neue API-Parameter hinten anfügen, damit bestehende Aufrufe weiter funktionieren Die Reihenfolge von Parametern und Feldern exportierter Laufzeit-Programmierschnittstellen ist ein Vertrag, kein Umsetzungsdetail. - Bewahre die positionsbezogene Bedeutung bestehender öffentlicher Konstruktorargumente und Datenklassenfelder. Füge nie einen neuen Parameter oder ein neues Feld mitten in die bestehende öffentliche Reihenfolge ein. - Hänge neue optionale öffentliche Felder oder Parameter ans Ende an und behalte die ursprüngliche Reihenfolge der bestehenden Felder bei. - Ist eine Umordnung unvermeidlich, ergänze eine ausdrückliche Kompatibilitätsschicht sowie Regressionstests, die das alte positionsbasierte Aufrufmuster durchspielen. - Bevorzuge an Aufrufstellen benannte Argumente, um versehentliche Brüche zu vermeiden, aber rechtfertige damit nie das Brechen der positionsbezogenen Kompatibilität. - Behandle vorgesehene Importpfade und öffentliche Exportlisten als Verträge. Wenn du ein öffentliches Symbol hinzufügst oder verschiebst, aktualisiere das zuständige Modul, die vorgesehenen Re-Exporte auf oberster Ebene oder im Unterpaket sowie einen Regressionstest für den Import. - Halte Importe auf oberster Ebene frei von Fehlschlägen durch optionale Abhängigkeiten und von Nebeneffekten zur Laufzeit; nutze bei Bedarf verzögerte Exporte. ## Kompatibilität am letzten Release messen und größere Arbeit planen Beurteile Änderungen mit Bruchwirkung anhand der letzten Veröffentlichung, nicht anhand unveröffentlichter, zweiglokaler Zwischenstände. Schnittstellen, die nach der letzten Veröffentlichung eingeführt oder geändert wurden, dürfen direkt umgeschrieben werden, ohne Kompatibilitätsbehelfe, sofern sie keine veröffentlichte oder ausdrücklich unterstützte dauerhafte externe Zustandsgrenze festlegen oder der Nutzer ausdrücklich einen Migrationspfad verlangt. Unveröffentlichte gespeicherte Formate dürfen vor der Veröffentlichung neu nummeriert oder zusammengefasst werden, wenn Zwischenstände absichtlich nicht unterstützt werden. Bevorzuge bei zweiglokalen Zwischenständen nach der Veröffentlichung den direkten Ersatz gegenüber Kompatibilitätsschichten. Weise frühzeitig auf Kompatibilitätsrisiken hin – aber nur, wenn die Änderung Verhalten betrifft, das mit der letzten Veröffentlichung ausgeliefert wurde, oder eine veröffentlichte, unterstützte dauerhafte Zustandsgrenze – und stimme die Vorgehensweise ab, bevor du sie umsetzt. Nutze einen Ausführungsplan, wenn die Arbeit mehrstufig ist, mehrere Dateien umfasst, neue Funktionen oder Umbauten beinhaltet oder voraussichtlich länger als etwa eine Stunde dauert. Halte seine lebenden Abschnitte (Fortschritt, Erkenntnisse, Entscheidungsprotokoll, Ergebnisse) während der Ausführung aktuell und schreibe den Plan neu, wenn sich der Umfang verschiebt. Wenn du bei einer komplexen Aufgabe bewusst auf einen Plan verzichtest, vermerke den Grund, damit Prüfende die Entscheidung nachvollziehen können. ## Erst die Referenz des Teilsystems lesen, dann jede betroffene Stelle anpassen Die Laufzeitumgebung einer Bibliothek besteht aus mehreren zusammenwirkenden Teilsystemen – der Ausführungsschleife, der Werkzeugausführung, den Adaptern für Modelle und Anbieter, der Ablaufverfolgung, Sitzungen und dauerhafter Speicherung, Echtzeit- und Sprachpipelines, der Sandkasten-Isolierung sowie dem serialisierten Ausführungszustand. Bevor du eines davon änderst, lies die zugehörige Architekturreferenz und vergewissere dich, dass du die Grenze verstehst, die du berührst. Wenn du eine Variante hinzufügst oder änderst, die sich systemweit auswirkt – etwa einen neuen Typ für Modellausgabe, Werkzeugaufruf, Genehmigung oder Ausführungselement –, aktualisiere jede betroffene Stelle: Verarbeitung, Ereignisse, Wiedergabe, dauerhafte Speicherung, Ablaufverfolgung und Serialisierung. Wird eine Stelle übersehen, entsteht eine schwer nachvollziehbare, schleichende Beschädigung. Halte das Verhalten von Streaming- und Nicht-Streaming-Pfaden aufeinander abgestimmt. Prüfe bei jedem Teilsystem, das Verbindungen, Aufgaben oder andere Ressourcen verwaltet, die Ressourcenzuständigkeit sowohl auf dem normalen Pfad als auch auf dem Fehlerpfad. Ändert sich die Struktur eines serialisierten Ausführungszustands, befolge für dieses Format die Regeln zu Veröffentlichungsgrenzen, Schemaversion, Rückwärtslesbarkeit und Regressionstests. ## Dokumentation an den echten Code anpassen und sensible Daten aus Logs heraushalten - Dokumentation wird oft auf einer Live-Website veröffentlicht, daher stimme Verhaltensänderungen und Dokumentation sorgfältig aufeinander ab. Würde die Dokumentation ein noch nicht veröffentlichtes Verhalten beschreiben, verschiebe die Dokumentationsänderung, bis die Veröffentlichung verfügbar ist, oder teile sie in eine Folgeänderung auf. - Behandle ausführbare Dokumentationsausschnitte als Prüfungen der Kompatibilität von Programmierschnittstellen. Bevor du Beispiele für Konstruktoren oder Programmierschnittstellen hinzufügst, überprüfe die gezeigten Argumente und die Aufrufform anhand der tatsächlichen Umsetzung. - Lass nicht zu, dass nicht vertrauenswürdige Sandkasten- oder Verzeichnisdaten sich selbst aus den Grenzen des Wirtsdateisystems oder des Basisverzeichnisses herausnehmen. Ausweichmöglichkeiten für die lokale Materialisierung müssen von vertrauenswürdigem Anwendungscode an der Aufrufstelle gesteuert werden, niemals von serialisierten Verzeichnisdaten. - Wenn du eine Sicherheitsberechtigung oder -grenze dokumentierst, überprüfe, ob der tatsächliche Codepfad sie auch durchsetzt. Behaupte nicht, dass eine Berechtigung für einen Materialisierungspfad (lokales Verzeichnis, lokale Datei, Archiventpackung) gilt, wenn dieser Pfad sie nicht tatsächlich abfragt. - Wenn du sensible Nutzdaten schwärzt, berücksichtige die Anzeige von Rückverfolgungen, die Verkettung von Ausnahmen, beibehaltenen Ausnahmekontext, Protokolle und Telemetriedaten. Das Unterdrücken einer Rückverfolgung reicht nicht aus, wenn das ursprüngliche Ausnahmeobjekt weiterhin sensible Eingaben enthält. ## Formatierungs- und Testprüfungen bestehen, dann eine Pull-Request-Übergabe schreiben Erweitere die Tests, sobald du Code berührst, und stelle sicher, dass die relevanten Prüfungen bestehen, bevor du die Änderung einreichst. - Führe die vollständige Testsammlung aus; nutze während der Bearbeitung gezielte Testläufe nach Muster. - Führe die statische Typprüfung aus; Typhinweise müssen bestehen. - Erzeuge bei snapshot-basierten Tests die Snapshots bewusst neu und führe die Testsammlung anschließend erneut aus. - Die Testabdeckung muss über dem Schwellenwert des Projekts bleiben. - Wende den Formatierer und den Codeprüfer an; halte Importe sortiert; schreibe Kommentare als vollständige Sätze mit abschließendem Punkt. - Führe die Prüfungen in der vom Projekt vorgeschriebenen Reihenfolge aus – zuerst Formatierung, dann Codeprüfung, dann Typprüfung, dann Tests. Für Pull-Requests und Commits gilt: - Nutze die PR-Vorlage des Projekts: Füge eine Zusammenfassung, einen Testplan und gegebenenfalls das zugehörige Issue hinzu. - Schreibe knappe Commit-Nachrichten im Imperativ; halte Commits klein und fokussiert. - Füge Tests für neues Verhalten hinzu und aktualisiere die Dokumentation bei jeder für Nutzende sichtbaren Änderung. - Erstelle vor deiner abschließenden Antwort zu einer dafür infrage kommenden Änderung einen PR-Übergabeblock (Zusammenfassung, vorgeschlagener Zweigname, Titel, Entwurfsbeschreibung). Das Erstellen dieser Übergabe berechtigt für sich genommen nicht dazu, einen Zweig anzulegen, einen Commit zu erstellen, zu pushen oder einen Pull-Request zu eröffnen; lasse sie nur bei trivialen Aufgaben oder reinen Gesprächsaufgaben weg, bei übergeordneten Aufgaben oder reinen Dokumentationsaufgaben ohne Verhaltensauswirkung, oder wenn der Nutzer sagt, sie nicht einzuschließen. Prüfende achten auf: bestandene Prüfungen; Tests, die neues Verhalten und Randfälle abdecken; lesbaren, einheitlichen Code; dokumentierte Änderungen an öffentlichen Programmierschnittstellen und für Nutzende sichtbare Änderungen; aktualisierte Beispiele bei Verhaltensänderungen; sowie eine saubere Historie mit klarer Beschreibung.