Eine verwaltete Bindungsschicht und ihre native Bibliothek ändern, ohne die ABI zu brechen

## Jede Änderung von der verwalteten Schicht bis zum nativen Code verfolgen Behandle die Bibliothek als Schichtensystem aus verwalteter Bindungsschicht, Interoperabilitätsdeklarationen, stabiler C-kompatibler API und nativer Implementierung. - Prüfe öffentliche Eingaben in der verwalteten Bindungsschicht. - Halte die C-kompatible Brücke klein und vorhersehbar; sie soll übersetzen und weiterleiten, nicht Regeln doppelt umsetzen. - Sorge für exakte Übereinstimmung zwischen verwalteten Deklarationen, exportierten C-Symbolen, Parametertypen, Rückgabetypen und nativen Implementierungen. - Lege vor einer Codeänderung fest, welche Schicht für jede Prüfregel, Speicherzuweisung, Fehlerumwandlung und Lebensdauerübergabe zuständig ist. - Verfolge eine Änderung durch alle betroffenen Schichten, statt nur den ersten Übersetzungsfehler zu beheben. Eine Änderung, die in der verwalteten Schicht übersetzt wird, kann zur Laufzeit weiterhin scheitern, wenn der nativen Binärdatei das neue Symbol fehlt oder sie eine andere Signatur verwendet. ## Je nach Änderung vorgefertigte oder selbst gebaute native Binärdateien wählen Native Binärdateien müssen vorhanden sein, bevor die verwaltete Bindungsschicht erstellt werden kann. Ihre richtige Quelle hängt jedoch von der Art der Änderung ab. - Verwende bei ausschließlich verwalteten Änderungen die vom Quellcodearchiv freigegebenen vorkompilierten nativen Artefakte des aktuell veröffentlichten Meilensteins. - Erstelle bei Änderungen an nativer Implementierung, C-API, Abhängigkeiten, Untermodulen, Versionen oder Meilensteinen die nativen Binärdateien aus dem Quellcode für Zielplattform und Zielarchitektur. - Nach jeder Änderung mit Auswirkung auf die native Seite ist das Herunterladen der aktuellen vorkompilierten Binärdateien verboten, bis die Änderungen an der Artefaktquelle veröffentlicht wurden. - Schlägt die native Quellkompilierung fehl, untersuche ihre Werkzeugkette sowie Abhängigkeits-, Pfad- oder Netzvoraussetzungen. Greife niemals nur deshalb auf veraltete Downloads zurück, damit die verwaltete Erstellung erfolgreich erscheint. - Bereinige Plattformzwischenspeicher, wenn sie ein älteres natives Modul behalten und falsche Prüfergebnisse erzeugen können. Veraltete native Binärdateien können nach einer API-Änderung einen unbemerkt falschen Build erzeugen, auf den zur Laufzeit Fehler wegen fehlender Einsprungpunkte folgen. ## Bindungscode neu erzeugen statt ihn zu bearbeiten und die ABI stabil halten Bearbeite erzeugten Bindungscode, erzeugte Dokumentation, gerenderte Veröffentlichungsseiten oder andere ausdrücklich erzeugte Ausgaben niemals von Hand. Ändere die bearbeitbare Quelle und führe nach jeder Änderung an der C-API den Generator des Quellcodearchivs aus. Halte die binäre Anwendungsschnittstelle stabil: - Füge Überladungen, Methoden oder Typen hinzu, statt vorhandene Signaturen zu ändern. - Entferne keine öffentlichen APIs und ändere ihre Rückgabetypen nicht. - Bevorzuge Überladungen gegenüber neuen Standardparametern, da Standardparameter die Binärkompatibilität verändern können. - Kennzeichne eine API als veraltet, statt sie zu entfernen, und gib umsetzbare Hinweise zur Umstellung. - Halte Benennungs- und Parameterkonventionen mit den umgebenden öffentlichen APIs konsistent. - Erzeuge den Bindungscode neu und prüfe die entstandenen Unterschiede vor der Kompilierung. Wenn die Dokumentation erzeugte Seiten und bearbeitbare Quelldateien als Beistellungen enthält, ändere nur die vorgesehene Quelle und erzeuge die Ausgabe erneut. ## Besitz nativer Zeiger einordnen und veränderbare Objekte nicht zwischen Threads teilen Ordne jeden nativen Zeiger ein, bevor du eine Bindungsschicht schreibst: - Ein ausgeliehener Parameter überträgt keinen Besitz. - Ein manuell besessenes natives Objekt benötigt den nativen Freigabepfad der Bindungsschicht. - Ein referenzgezähltes Objekt muss den Referenzzählvertrag der Bindungsschicht verwenden. Passe das Fehlerverhalten an die jeweilige Schicht an. Die C-kompatible API gibt einen Nullzeiger oder `false` zurück; eine verwaltete Fabrikmethode gibt `null` zurück; ein verwalteter Konstruktor löst eine Ausnahme aus, wenn er kein gültiges Objekt herstellen kann. Einige native Operationen können dieselbe Instanz zurückgeben, die sie erhalten haben. Vergleiche die Identitäten, bevor du die Quelle freigibst. Andernfalls kann der Rückgabewert auf ein bereits freigegebenes Objekt verweisen. Teile veränderliche native Objekte nicht zwischen Threads, sofern der native Vertrag dies nicht ausdrücklich erlaubt. Gib jedem Thread seinen eigenen veränderlichen Zustand; teile nur Objekte, die als unveränderlich und threadsicher dokumentiert sind. Übergib niemals einen vorübergehend fixierten verwalteten Zeiger an nativen Code, der ihn über den Fixierungsbereich hinaus behalten kann. Verwende ein fixiertes Handle mit ausdrücklicher Lebensdauer oder reserviere nicht verwalteten Speicher. Ein Verstoß ermöglicht der Speicherbereinigung, den Speicher zu verschieben, während der native Code noch die alte Adresse hält. ## Im Hauptarchiv und im nativen Submodul eigene Feature-Zweige nutzen Erstelle einen Funktionszweig, bevor du Änderungen festschreibst. Schreibe niemals direkt in geschützte Zweige. Wende dieselbe Regel unabhängig auf ein natives Untermodul oder ein verschachteltes Quellcodearchiv an: Es besitzt einen eigenen Zweigzustand, eigene geschützte Zweige, Festschreibungen und einen eigenen Prüfweg. 1. Erstelle im übergeordneten Quellcodearchiv einen zielgerichteten Funktionszweig. 2. Wenn das verschachtelte native Archiv geändert wird, erstelle dort vor Bearbeitung oder Festschreibung einen eigenen Funktionszweig. 3. Halte alle Festschreibungen in den zugehörigen Funktionszweigen. 4. Reiche Änderungen über das vom Quellcodearchiv freigegebene Prüfverfahren für Änderungsanträge ein. 5. Bestätige, dass das übergeordnete Archiv die vorgesehene und geprüfte native Revision verzeichnet. Ändere keine vom Ursprungsprojekt verwalteten nativen Verzeichnisse außerhalb der vom Quellcodearchiv festgelegten Anpassungs- oder Erweiterungsfläche. ## Mit den richtigen nativen Binärdateien testen und keine Fehler überspringen Eine erfolgreiche Kompilierung ist kein Abschluss. Führe die einschlägigen verwalteten Tests gegen native Binärdateien aus, die über den richtigen Bereitstellungspfad erzeugt wurden. - Die Tests müssen erfolgreich sein, bevor du den Abschluss meldest. - Überspringe keinen fehlgeschlagenen Test und führe keine Ausnahme zum Überspringen ein, um eine Regression zu umgehen. - Überspringen ist nur bei einer nachgewiesenen Hardware- oder Plattformbeschränkung zulässig, etwa bei fehlender Anzeige, nicht verfügbarem Grafikgerät oder einer von der Plattform nicht unterstützten Funktion. - Erzeuge den Bindungscode vor dem Test neu, wenn sich die C-API geändert hat. - Bereinige zwischengespeicherte native Web- oder Plattformartefakte, bevor du Versionsänderungen prüfst. - Prüfe bei Änderungen mit Auswirkung auf die native Seite repräsentative Plattformen und Architekturen. Schreibe Tests, die bei falschem Besitz, falscher Nullwertbehandlung, falschen Exportsymbolen, falscher ABI, falschem Threadbereich oder falscher Freigabe scheitern. Ergänze bei Leistungsänderungen Gleichwertigkeitstests und Leistungsmessungen, wenn das genaue Verhalten oder der Nutzen noch nicht nachgewiesen ist. ## Schichtübergreifende Fehler an ihrem Fehlerbild erkennen Stelle einen bekanntermaßen funktionierenden Ausgangszustand her, ändere jeweils nur eine Variable, protokolliere jedes Ergebnis und behandle Plattformunterschiede als Beleg. Wenn eine Änderung den Zustand verschlechtert, nimm sie zurück, bevor du eine andere Hypothese prüfst. Nutze die Fehlerform, um die zuerst zu untersuchende Grenze auszuwählen: - Ein fehlender verwalteter Typ deutet darauf hin, dass der Bindungscode nicht neu erzeugt oder nicht eingebunden wurde. - Ein nicht auflösbares natives Symbol deutet auf eine Abweichung zwischen C-Deklaration und Implementierung hin. - Ein zur Laufzeit fehlender Einsprungpunkt weist stark auf veraltete native Binärdateien oder einen nicht passenden Export hin. - Eine Zugriffsverletzung deutet auf beschädigte Besitz-, Freigabe-, Fixierungs- oder Signaturregeln hin. - Ein Nullverweisfehler nach einem Fabrikaufruf deutet darauf hin, dass die native Schicht einen Fehler zurückgab und der Aufrufer ihn ignorierte. - Zufällige Abstürze über Threadgrenzen hinweg deuten auf gemeinsam genutzte veränderliche native Objekte hin. Prüfe vor dem Abschluss die erzeugten Unterschiede, kompiliere bei Bedarf den nativen Code, kompiliere die verwaltete Bindungsschicht, führe Tests aus und prüfe die betroffene Plattformmatrix. Melde die genaue Quelle und Architektur der verwendeten Bereitstellungsartefakte. Melde keinen Erfolg, wenn Tests fehlschlagen, erforderliche native Quellkompilierungen durch Downloads ersetzt wurden oder die Plattformprüfung unvollständig ist.