Thema: compatibility
-
Protocol Buffers: Feldnummern, unbekannte Felder und die Regeln für die Weiterentwicklung einer Nachricht
In Protocol Buffers identifiziert die Feldnummer, nicht der Name, ein Feld auf der Leitung, weshalb Nummern nie geändert oder wiederverwendet werden dürfen; das Hinzufügen von Feldern ist unbedenklich, das Entfernen nur dann sicher, wenn die Nummer nie wiederverwendet wird (eine reserved-Anweisung erzwingt das), alte Leser behalten unbekannte Felder, und die Erweiterung von int32 zu int64 ist nur bedingt sicher. ProtoJSON hat eigene, davon abweichende Regeln.
-
Das Vergleichen des OpenAPI-Dokuments in der CI erkennt Breaking Changes, die im Code-Review übersehen werden
Hypothese: Ein CI-Schritt, der das OpenAPI-Dokument jeder Änderung mit einem Breaking-Change-Klassifikator wie oasdiff gegen das veröffentlichte Dokument vergleicht, markiert entfernte Felder, verengte Typen und neue Pflichtparameter, die beim menschlichen Review des Code-Diffs übersehen werden, sodass weniger unbeabsichtigte Breaking Changes in ein Release gelangen.
-
Eine Funktion in einer Bibliothek als veraltet markieren: warnen, den Ersatz dokumentieren, planmässig entfernen
Eine Deprecation in einer Bibliothek besteht aus vier Teilen: einem Ersatz, der zuerst existiert, einer Laufzeitwarnung zusammen mit einem Dokumentationshinweis, der Version und Ersatz nennt, einem Eintrag im Changelog und einer Entfernungs-Version, die im Voraus durch eine Richtlinie festgelegt wird. PEP 387 verlangt bei Pythons jährlichem Rhythmus eine Deprecation-Frist von mindestens zwei Jahren und beschreibt eine rein dokumentarische «Soft Deprecation»; Django entfernt Übergangslösungen (Shims) frühestens zwei Feature-Releases nach der Warnung.
-
Schema-Evolution mit Avro und Parquet: Reader- und Writer-Schemas, zusammengeführte Dateien und Kompatibilitätsmodi
Avro gleicht das Schema eines Writers Feld für Feld mit dem Schema eines Readers ab, füllt fehlende Felder aus den Standardwerten des Readers und ignoriert unbekannte Felder; Parquet-Dateien mit unterschiedlichen, aber kompatiblen Schemas kann die lesende Engine mit einem gewissen Aufwand zusammenführen; eine Schema-Registry erzwingt Rückwärts-, Vorwärts- oder vollständige Kompatibilität. Optionale Felder mit Standardwerten hinzuzufügen ist der sichere Weg, Umbenennungen und Typänderungen sind es nicht.
-
Einen API-Endpunkt mit den Headern Deprecation und Sunset abkündigen
Das End of Life im Band ankündigen: Der Header Deprecation (RFC 9745) markiert eine Ressource als veraltet, der Header Sunset (RFC 8594) gibt an, wann sie nicht mehr funktionieren wird, und ein Link zur Dokumentation erklärt den Ersatz; dazu passend werden die verbleibenden Aufrufer protokolliert.
-
Supporting several release lines: which fixes go where
A support policy is a table of release lines with a status each (feature, bugfix, security-only, end of life) and a rule for which fix classes are backported to which lines. Python maintains a series with bugfix releases for two years and security-only releases for three more; Django backports critical fixes to the last feature release and security and data-loss fixes to the last two plus long-term-support lines; Rust supports only the most recent stable. A small project should publish the table and default to the narrowest promise it can keep.
-
Match claims to the version they cover
Represent version scope explicitly and refuse to apply a current-documentation claim to an unknown or incompatible installation.
Maschinenlesbar: JSON