Richtlinien für Den Daten-API-Generator
Eine Reihe von Richtlinien steuert den Daten-API-Generator im Zusammenhang mit breaking Changes, Benachrichtigungen, Releases und Versionsverwaltung.
Versionsverwaltung und Releases
Ein Release im Kontext des Daten-API-Generators bezieht sich auf jede veröffentlichte Version der Software, die durch das Major.Minor.Patch Format identifiziert wird. Diese Releases lassen sich in drei Kategorien einteilen: Stabil, Breaking Change und Vorschau.
Stabile Releases
Eine stabile Version des Daten-API-Generators ist abwärtskompatibel. Abwärtskompatibel bedeutet, dass jeder Von Ihnen geschriebene Code, der auf einer Version eines Daten-API-Generators basiert, eine neuere stabile Version übernehmen kann, ohne dass Codeänderungen erforderlich sind, um die Richtigkeit oder vorhandene Funktionalität aufrechtzuerhalten.
Breaking Change Releases
Eine Breaking Change-Version des Daten-API-Generators ist nicht abwärtskompatibel. Die Übernahme einer Breaking Change-Version in vorhandenem Clientcode erfordert möglicherweise Codeänderungen, um sicherzustellen, dass sich der Client genau wie beim Ziel der vorherigen Version verhält.
Breaking Change-Versionen werden über den Artikel Breaking Change List und in der Änderungsbeschreibung einer GitHub-Version angekündigt. Die Veröffentlichung einer Vorschau-/Release-Kandidatenversion geht vor Breaking Change-Versionen vor, es sei denn, die Änderungen beheben wichtige Sicherheits-, Datenschutz- oder rechtliche Probleme. Frühere Versionen des Daten-API-Generators bleiben zwar auf der GitHub-Releaseseite verfügbar, es wird jedoch empfohlen, ein Upgrade auf die neueste Version durchzuführen, die möglicherweise Fehlerbehebungen enthalten kann.
Vorschaureleases
Vorschauversionen des Daten-API-Generators werden mit dem X.Y.Z-rc Versionsschema identifiziert. Das -rc Suffix gibt an, dass der Build ein "Release Candidate" ist. Vorschauversionen werden verwendet, um Feedback zu neuen Features und anderen Änderungen zu sammeln.
Sofern wir nicht beabsichtigen, wesentliche Änderungen ab der letzten stabilen Version vorzunehmen, veröffentlichen wir die nächste Vorschauversion mit allem, was die neueste stabile Version und neue Vorschaufeatures umfasst. Das nächste Daten-API-Generator-Update kann einige der neuen Vorschaufeatures, die wir zwischen den Vorschauversionen hinzugefügt haben, unterbrechen. Dieses Breaking-Verhalten bedeutet, dass Sie Ihren Code möglicherweise ändern müssen, damit die Dinge wieder funktionieren.
Vorschauversionen sind nicht für den langfristigen oder produktionsseitigen Einsatz vorgesehen. Wenn eine neue stabile Oder Vorschauversion verfügbar wird, kann auf ältere Vorschauversionen möglicherweise nicht mehr zugegriffen werden. Es ist am besten, Vorschauversionen nur zu verwenden, wenn Sie aktiv an neuen Features arbeiten und bald nach der Veröffentlichung zu einer Nicht-Vorschauversion wechseln können. Wenn einige Features aus einer Vorschauversion in einer neuen stabilen Version enthalten sind, werden die verbleibenden Vorschaufeatures einer neuen Vorschauversion hinzugefügt, die Sie ausprobieren können.
Versionsänderungstabelle
Wichtig
Möglicherweise führen wir eine breaking Change an einem Neben- oder Patchrelease ein, wenn die Änderung kritische Produktfehler, rechtliche, Sicherheits- oder Datenschutzbedenken behandelt.
| Freigabetyp | Vorherige Version | Neue Version | Hinweise |
|---|---|---|---|
| Unterbrechende Änderung | 1.Y.Z |
2.Y.Z |
Neue Features und Fehlerbehebungen sowie alle breaking changes. |
| Stable | 1.1.Z |
1.2.Z |
Neue Features und Fehlerbehebungen ohne Breaking Changes, es sei denn, die Änderungen behandeln kritische Produktfehler, rechtliche, Sicherheits- oder Datenschutzbedenken. |
| Stable | 1.1.1 |
1.1.2 |
Fehlerbehebungen ohne neue Features oder breaking Changes, es sei denn, die Änderungen behandeln kritische Produktfehler, rechtliche, Sicherheits- oder Datenschutzbedenken. |
| Vorschau | X.Y.1-rc |
X.Y.2-rc |
Neue Vorschaufeatures und Fehlerbehebungen. (Breaking changes are included if the major version is bumped.) |
Aktuelle Änderungen
Um Die Sicherheit zu priorisieren, Features zu verbessern und die Codequalität zu gewährleisten, können neue Versionen unserer Software breaking changes enthalten. Obwohl wir versuchen, diese Änderungen durch sorgfältige Architekturentscheidungen zu minimieren, können sie dennoch auftreten. In solchen Fällen haben wir priorität, sie anzukündigen und mögliche Lösungen bereitzustellen.
Wichtig
Wir können Änderungen ohne vorherige Ankündigung vornehmen, wenn die Änderung als nicht breaking gilt oder wenn es sich um eine breaking Änderung handelt, die vorgenommen wird, um kritische Produktfehler oder rechtliche, Sicherheits- oder Datenschutzbedenken zu beheben.
Was ist eine breaking change?
Bei einer Breaking Change handelt es sich um eine Änderung, bei der Sie Ihre Anwendung aktualisieren müssen, um Unterbrechungen zu vermeiden. Im Daten-API-Generator können Breaking Changes Änderungen an REST-API-Verträgen, GraphQL Schemagenerierung und andere Elemente umfassen, die sich auf Kompatibilität und Funktionalität auswirken.
Beispiele für Breaking Change
Die folgenden Beispiele sind eine nichtexhaustive Liste der breaking changes am Data API Builder:
- Rest-API-Vertragsänderungen
- Änderungen bei GraphQL Schemagenerierung
- Änderungen, die sich auf die Abwärtskompatibilität auswirken
- Entfernen oder Umbenennen von APIs oder Parametern
- Änderungen an Fehlercodes
- Anpassungen der Berechtigungsdefinitionsfunktionalität
- Entfernen zulässiger Parameter, Anforderungsfelder oder Antwortfelder
- Hinzufügen von obligatorischen Parametern oder Anforderungsfeldern ohne Standardwerte
- Änderungen an der beabsichtigten API-Endpunktfunktionalität
Definition einer nicht unterbrechenden Änderung
Eine nicht breaking Änderung bezieht sich auf eine Änderung, die ohne Unterbrechung in Ihre Anwendung integriert werden kann. Nicht unterbrechende Änderungen werden in der Regel nach der Implementierung mitgeteilt. Ihre Anwendung sollte so konzipiert sein, dass sie diese Änderungen ohne vorherige Ankündigung verarbeitet.
Beispiele für unterbrechungsfreie Änderungen
Die folgenden Beispiele sind eine nichtexhaustive Liste der nicht unterbrechungsfreien Änderungen am Daten-API-Generator:
- Einführung neuer Endpunkte
- Hinzufügen von Methoden zu vorhandenen Endpunkten
- Einbindung neuer Felder in Antworten und Anforderungen
- Anpassungen der Feldreihenfolge innerhalb von Antworten
- Einführung optionaler Anforderungsheader
- Änderungen an Datenlänge und Antwortgröße
- Änderungen an Fehlermeldungen und Codes
- Korrekturen für HTTP-Antwortcodes
- Zusätzliche Metadaten in generierten OpenAPI-Dokumenten
Wie kommunizieren wir breaking changes?
Wir legen es zur Priorität, Sie umgehend über breaking changes zu informieren. Benachrichtigungen zu breaking change finden Sie in den Versionshinweisen der Data API Builder-Versionen auf GitHub und im Artikel Zur Liste der dedizierten Breaking Changes.
Aktuelle Breaking Change-Liste
In diesem Artikel werden breaking changes and feature retirements angekündigt.
- Derzeit gibt es keine Breaking Changes