Versionnage de l'API

Deux versions comptent quand vous construisez sur cmssy, et une seule figure dans votre lockfile. "@cmssy/core": "16.9.0" épingle le client. L'API de diffusion qu'il appelle est un service hébergé qui se déploie à son propre rythme, et aucun segment de version n'est disponible pour l'épingler à la place.

Cette page dit clairement ce que cela implique, y compris ce que nous ne garantissons pas encore.

Ce que couvre la version du paquet

Du semver classique, et uniquement pour ce paquet : ses exports, leurs signatures, son comportement. Un majeur signifie que votre code devra peut-être changer. Cela ne dit rien du schéma à l'autre bout : un champ retiré du schéma de diffusion a disparu pour @cmssy/core@16.9.0 exactement comme pour la version suivante.

Ce qui vous protège aujourd'hui

• La surface de diffusion est une liste blanche. L'endpoint sous /public/{org}/{workspace}/graphql sert un sous-ensemble délibérément choisi du schéma, pas tout ce que voit l'API d'administration. Un champ s'y trouve parce que quelqu'un l'y a mis.
• Un changement cassant ne peut pas être fusionné en silence. Chaque modification du schéma est comparée à la précédente dans la CI. Une suppression ou un rétrécissement fait échouer la barrière, et l'expédier malgré tout exige une approbation explicite et consignée.
• Les opérations publiées sont validées. Les requêtes du SDK lui-même, celles du serveur MCP et celles de la boutique de référence sont exécutées contre le schéma proposé avant toute fusion.
• Les suppressions sont signalées d'abord. Un champ que nous comptons retirer est marqué @deprecated dans le schéma, ce qui apparaît dans votre sortie de codegen et dans votre éditeur.

Ce qui n'existe pas encore

Dit, plutôt que sous-entendu :

• Il n'y a aucune version d'API datée à épingler. L'endpoint de diffusion n'a pas de segment de version.
• Il n'y a aucune fenêtre de dépréciation garantie. @deprecated marque une intention ; ce n'est pas la promesse que le champ survivra un nombre de jours défini.
• Il n'y a aucun préavis minimum, ni liste d'annonces à laquelle s'abonner.

Nous préférons l'écrire plutôt que de laisser un numéro de version suggérer une promesse que le serveur ne tient pas.

Que faire

Générez vos types depuis l'endpoint de diffusion, pas depuis le schéma d'administration. Il est plus étroit, et typer contre lui fait échouer votre build sur un champ que vous n'aviez de toute façon pas le droit de lire :

// codegen.ts
schema: `${process.env.CMSSY_API_URL}/public/${org}/${workspace}/graphql`,
documents: ["app/**/*.tsx", "lib/**/*.ts"],

Exécutez le codegen dans votre propre CI, pas seulement sur votre machine. Si un champ que vous sélectionnez disparaît, le codegen échoue là - et c'est le plus tôt que quiconque hors de cmssy puisse l'apprendre.

Épinglez le SDK et mettez à jour délibérément. Cela ne vous protège pas des changements de schéma, mais évite que le comportement du client bouge sous vos pieds en même temps.