# Release-Züge, Notizen und Abkündigungen

Die API ändert sich in Zügen: Ein Zug bindet die Fassungen der Dienste zu einem Datum zusammen, und zu jedem Zug entsteht eine Notiz, die Brüche vor allem anderen nennt. Diese Seite sagt, wie beides aufgebaut ist, wo die Notizen heute stehen und was für Abkündigungen gilt.

> **Typ:** nachschlagen
> **Für wen:** Wer eine Integration betreibt und wissen will, in welcher Form Änderungen an der API angekündigt werden.
> **Voraussetzung:** keine. Die Spezifikation unter `https://developer.szenera.com/api/openapi.json` ist ohne Anmeldung erreichbar.

## Der Release-Zug

Ein Zug ist ein Schnitt durch die Zeit, kein Versionsvertrag. Er trägt darum kein eigenes Major, Minor oder Patch, sondern sein Datum.

| Merkmal | Was gilt |
|---|---|
| Name | `release/JJJJ-MM-TT`, bei mehreren Zügen am selben Tag `release/JJJJ-MM-TT.2` (ein `.1` gibt es nie) |
| Was er transportiert | die Dienste der Plattform: die API, das Portal, das Betreiber-Portal, die Startseite und die Anzeige-Anwendung der Bildschirme |
| Fassungen | jeder Dienst trägt seine eigene Zahl (etwa `0.4.14`); der Zug führt nur die Dienste als bewegt, deren Zahl seit dem letzten Zug gestiegen ist; die übrigen stehen als *unverändert* in der Notiz |
| Wann ein Zug fällig ist | sobald die Fassung eines dieser Dienste über der des letzten Zugs liegt — in der Praxis, wenn die gesammelten Änderungsnotizen zu neuen Fassungen werden |
| Was der Zug ausliefert | dieselben Abbilder, die zuvor auf Staging liefen — sie werden nicht neu gebaut, nur mit ihrer Fassung etikettiert |
| Was nicht im Zug reist | das Betriebssystem der Player — es folgt einem eigenen Takt und eigenen Auslösern; ebenso die Display-Erweiterung für den Browser. Bibliotheken wie API-Client und Apps-SDK sowie die Apps reisen in den Diensten mit; ihre Fassungen nennt die Notiz unter „Pakete“ |

Die Fassung des Dienstes, der in Ihrer Umgebung antwortet, nennt `GET /health/version` — ohne Anmeldung, mit den Feldern `service`, `version`, `builtAt` und `environment`. In Produktion steht in `version` nur die Zahl (`0.4.1`), auf allen anderen Umgebungen hängt das Commit-Kürzel des Baus an (`0.4.1+a1b2c3d`). Außerhalb eines Auslieferungs-Abbilds meldet die Route `unknown` oder eine Zahl mit dem Anhang `-dev`. Die Route ist auf 60 Aufrufe je Minute und Adresse begrenzt.

Die Spezifikation selbst trägt in `info.version` eine eigene Zahl. Sie ist eine Betreibereinstellung mit der Vorgabe `1.0.0` und bewegt sich nicht mit jedem Zug — was sich geändert hat, sehen Sie darum verlässlich nur am Inhalt der Spezifikation, nicht an dieser Zahl. Wie Sie den Inhalt vergleichen, steht auf [Die Spezifikation gegen Ihren Stand vergleichen](/de/changes/compare-specification).

## Wie eine Notiz aufgebaut ist

Der Text einer Notiz stammt aus den **Änderungsnotizen**, die jede Änderung an der Plattform mitbringt: Wer eine Änderung schreibt, legt dazu eine Notiz ab und schreibt darin je Paket Zeilen mit Art und Zielgruppe — für Kundinnen und Kunden, für den Betrieb, für Entwickler. Die Notiz eines Zugs richtet sich an den Betrieb: Sie nennt die Brüche und die Handgriffe des Ausrollens und verweist für Kunden und Entwickler auf ihre Seiten. Was niemand aufgeschrieben hat, behauptet sie nicht.

| Teil | Inhalt |
|---|---|
| Titel | `Szenera <Datum>` |
| Breaking changes | je Bruch für Entwickler und Betrieb eine Zeile mit Paket, Umstieg und Verweis auf die Änderung, die ihn gebracht hat |
| Ausrollen | die Handgriffe des Betriebs, durchgehend nummeriert: erst vor dem Ausrollen, dann beim Ausrollen, dann danach |
| Für Kunden | der Verweis auf die Änderungsseite des Handbuchs und die Zahl der Apps, die ihre Neuerungen im Store erklären |
| Für Entwickler | der Verweis auf die Änderungsliste je Paket und auf die Paketseite der Entwicklerfläche |
| Pakete | Bibliotheken, Apps und Erweiterung, deren Fassung mit dem Zug steigt, mit der Fassung davor |
| Auslieferung | eine Tabelle `Dienst · Fassung · vorher · Digest` über alle Dienste des Zugs |
| Vergleich | ein Verweis auf alle Änderungen seit dem letzten Zug |

Ein Zug ohne eine einzige Notiz sagt das in einem Satz und nennt nur die Fassungen.

## Was ein Bruch ist

Ein Bruch ist eine Änderung, die Sie zum Handeln zwingt: ein Pfad, der verschwindet oder umzieht, ein neues Pflichtfeld, ein anderer Fehlercode. Gekennzeichnet wird er in der Notiz selbst: Die Zeile trägt `breaking` und nennt den Umstieg, und die Stufe des Pakets steigt. Solange die erste Ziffer einer Fassung `0` ist, ist die **zweite** Ziffer die Bruchgrenze — `0.4.21` auf `0.5.0` ist ein Bruch, `0.4.21` auf `0.4.22` nicht. Was zu tun ist, steht als Umstieg wortgetreu so, wie es der Autor geschrieben hat; eine gekürzte Anweisung wäre eine falsche.

Ein Bruch steht im Abschnitt Breaking changes ganz oben. Bei den Paketen zeigt ihn zusätzlich die Änderungsliste: Dort steht er unter **Breaking changes** — siehe [Pakete und ihre Fassungen](/de/changes/packages).

## Was am Release hängt

| Anhang | Inhalt |
|---|---|
| `manifest.json` | der Zug maschinenlesbar: Dienste, Fassungen, Digests, gestiegene Pakete, verbrauchte Notizen |
| `openapi.json` | die Spezifikation im Stand dieses Zugs |
| zwei SBOMs (CycloneDX) | die Stücklisten der Abhängigkeiten aus demselben Stand |
| `SHA256SUMS` | Prüfsummen über alle Anhänge |

Ein fehlender Anhang hält den Zug nicht auf. Die Stücklisten entstehen in einem eigenen Lauf, der langsamer sein kann als der Zug; fehlt etwas, sagt die Notiz das in einer Zeile: „Nicht angehängt: … — im Lauf nicht beschaffbar“.

## Wo die Notizen heute stehen

Die Notizen entstehen als Release-Eintrag im Quellcode-Archiv der Plattform. Dieses Archiv ist nicht öffentlich, und diese Seite führt keine Einträge daraus. Verlässlich und ohne Anmeldung erreichbar sind fünf Dinge:

| Quelle | Was sie sagt |
|---|---|
| `https://developer.szenera.com/api/openapi.json` | die Spezifikation im Stand des aktuellen Zugs |
| `GET /v1/openapi.json` Ihrer Umgebung | die Spezifikation der Fassung, die dort tatsächlich läuft; die Antwort darf fünf Minuten zwischengespeichert werden (`Cache-Control: public, max-age=300`) |
| [Pakete und ihre Fassungen](/de/changes/packages) | Fassung und Änderungsliste von API-Client, Apps-SDK, CLI und Verträgen, Abschnitt für Entwickler |
| [Änderungen im Handbuch](https://szenera.com/de/docs/help/whats-new) | was sich je Zug in der Oberfläche geändert hat, das Neueste zuerst — ohne Anmeldung |
| [Der Status der Plattform](https://szenera.com/status) | der aktuelle Zustand, angekündigte Wartungsfenster und die letzten Störungen |

Beide Fassungen der Spezifikation können auseinanderliegen, wenn Ihre Umgebung einen älteren Zug fährt. Ein Vergleich der beiden Dateien ist darum der Weg, eine Änderung sicher zu erkennen.

## Was für Abkündigungen gilt

| Frage | Stand heute |
|---|---|
| Wie ist eine Operation gekennzeichnet? | Jede Operation trägt `x-stability` mit `stable`, `beta` oder `internal`. Heute sind 372 der 443 öffentlichen Operationen `stable`. |
| Was bedeutet `stable`? | Pfad, Pflichtfelder und Fehlercodes ändern sich nicht ohne neue Version. Ein Feld kann dazukommen, keines verschwindet. |
| Gibt es abgekündigte Operationen? | Heute keine. Käme eine dazu, trüge sie `deprecated: true` und `x-sunset` in der Beschreibung sowie `Deprecation`, `Sunset` und `Link` in jeder Antwort. |
| Gibt es ein Verfahren mit Fristen? | Ja: Zwischen Ankündigung und Abschaltung liegen **zwölf Monate**. Die Einzelheiten stehen unter [Stabilitätsklassen und Auslauf](/de/changes/stability-and-sunset). |
| Woran erkenne ich eine Änderung, die mich trifft? | Sie steht in der Notiz unter **Breaking changes**, ganz oben, mit wortgetreuem Handlungsbedarf — und sie zeigt sich im Vergleich der Spezifikationen. |
| Was ist mit Routen, die ich in der Referenz nicht finde? | Als `internal` gekennzeichnete Routen sind nicht Teil der öffentlichen Fläche; sie erscheinen in keiner Datei dieser Seite und in keiner Zusage. |

## Weiterführendes

- [Stabilitätsklassen und Auslauf](/de/changes/stability-and-sunset)
- [Die Spezifikation gegen Ihren Stand vergleichen](/de/changes/compare-specification)
- [Basis-URL, /v1 und Stabilität](/de/api/base-url-and-stability)