API-Versionierung
Die Version in deiner Lockfile pinnt den Client, nicht die gehostete API, die er aufruft. Was das heißt, was dich heute schützt und was wir noch nicht garantieren.
Beim Bauen auf cmssy zählen zwei Versionen, und nur eine davon steht in deiner Lockfile. "@cmssy/core": "16.9.0" pinnt den Client. Die Delivery-API, die er aufruft, ist ein gehosteter Dienst mit eigenem Deploy-Rhythmus - und es gibt kein Versionssegment, das du stattdessen pinnen könntest.
Diese Seite sagt klar, was das bedeutet, einschließlich dessen, was wir noch nicht garantieren.
Was die Paketversion abdeckt
Normales Semver, und nur für dieses Paket: seine Exports, deren Signaturen, sein Verhalten. Ein Major heißt, dass dein Code angepasst werden muss. Über das Schema am anderen Ende sagt es nichts - ein aus dem Delivery-Schema entferntes Feld ist für @cmssy/core@16.9.0 genauso weg wie für das nächste Release.
Was dich heute schützt
- Die Delivery-Oberfläche ist eine Allow-List. Der Endpunkt unter
/public/{org}/{workspace}/graphqlliefert eine bewusst gewählte Teilmenge des Schemas, nicht alles, was die Admin-API sieht. Ein Feld ist dort, weil jemand es dorthin gestellt hat. - Ein Breaking Change kann nicht stillschweigend mergen. Jede Schemaänderung wird in CI gegen die vorherige gediffed. Eine Entfernung oder Verengung lässt das Gate rot werden, und sie trotzdem auszuliefern erfordert eine ausdrückliche, festgehaltene Freigabe.
- Veröffentlichte Operationen werden validiert. Die Queries des SDK selbst, die des MCP-Servers und die des Referenz-Storefronts laufen vor dem Merge gegen das vorgeschlagene Schema.
- Entfernungen werden vorher markiert. Ein Feld, das wir streichen wollen, bekommt im Schema
@deprecated- das taucht in deiner Codegen-Ausgabe und in deinem Editor auf.
Was es noch nicht gibt
Ausgesprochen statt angedeutet:
- Es gibt keine datierte API-Version zum Pinnen. Der Delivery-Endpunkt hat kein Versionssegment.
- Es gibt kein garantiertes Deprecation-Fenster.
@deprecatedmarkiert die Absicht, verspricht aber nicht, dass das Feld eine feste Zahl von Tagen überlebt. - Es gibt keine Mindestvorlaufzeit und keine Ankündigungsliste, die du abonnieren könntest.
Lieber schreiben wir das hin, als eine Versionsnummer ein Versprechen andeuten zu lassen, das der Server nicht hält.
Was du tun kannst
Generiere deine Typen aus dem Delivery-Endpunkt, nicht aus dem Admin-Schema. Er ist schmaler, und dagegen zu typisieren heißt, dass dein Build an einem Feld scheitert, das du ohnehin nie lesen durftest:
// codegen.ts
schema: `${process.env.CMSSY_API_URL}/public/${org}/${workspace}/graphql`,
documents: ["app/**/*.tsx", "lib/**/*.ts"],Lass Codegen in deiner eigenen CI laufen, nicht nur lokal. Verschwindet ein Feld, das du selektierst, schlägt Codegen genau dort fehl - und das ist der früheste Moment, an dem jemand außerhalb von cmssy davon erfahren kann.
Pinne das SDK und aktualisiere bewusst. Das schützt dich nicht vor Schemaänderungen, hält aber das Verhalten des Clients davon ab, sich gleichzeitig unter dir zu bewegen.