Wersjonowanie API

Przy budowaniu na cmssy liczą się dwie wersje, a w Twoim lockfile siedzi tylko jedna. "@cmssy/core": "16.9.0" przypina klienta. API dostawcze, które ten klient woła, to usługa hostowana wdrażana we własnym rytmie - i nie ma segmentu wersji, który dałoby się przypiąć zamiast tamtego.

Ta strona mówi wprost, co z tego wynika, łącznie z tym, czego jeszcze nie gwarantujemy.

Co obejmuje wersja paczki

Zwykły semver i wyłącznie ta paczka: jej eksporty, ich sygnatury, jej zachowanie. Major znaczy, że Twój kod może wymagać zmiany. Nie mówi nic o schemacie po drugiej stronie - pole usunięte ze schematu delivery zniknęło dla @cmssy/core@16.9.0 dokładnie tak samo jak dla następnego wydania.

Co chroni Cię dzisiaj

• Powierzchnia delivery to lista dozwolonych. Endpoint pod /public/{org}/{workspace}/graphql serwuje celowo wybrany podzbiór schematu, a nie wszystko, co widzi API administracyjne. Pole jest tam dlatego, że ktoś je tam wstawił.
• Zmiana łamiąca nie wejdzie po cichu. Każda zmiana schematu jest w CI porównywana z poprzednim. Usunięcie albo zwężenie nie przechodzi przez bramkę, a wypuszczenie tego mimo wszystko wymaga wyraźnej, odnotowanej zgody.
• Opublikowane operacje są walidowane. Zapytania samego SDK, serwera MCP i referencyjnego sklepu idą przed mergem przeciwko proponowanemu schematowi.
• Usunięcie jest najpierw oznaczane. Pole, które zamierzamy usunąć, dostaje w schemacie @deprecated - widać to w wyniku codegenu i w edytorze.

Czego jeszcze nie ma

Powiedziane wprost, zamiast sugerowane:

• Nie ma datowanej wersji API do przypięcia. Endpoint delivery nie ma segmentu wersji.
• Nie ma gwarantowanego okna deprecjacji. @deprecated oznacza zamiar, a nie obietnicę, że pole przeżyje ustaloną liczbę dni.
• Nie ma minimalnego wyprzedzenia ani listy ogłoszeń, na którą dałoby się zapisać.

Wolimy to napisać, niż pozwolić, żeby numer wersji sugerował obietnicę, której serwer nie dotrzymuje.

Co z tym zrobić

Generuj typy z endpointu delivery, nie ze schematu administracyjnego. Jest węższy, więc typowanie względem niego sprawia, że build pada na polu, którego i tak nie wolno Ci czytać:

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

Odpalaj codegen w swoim CI, nie tylko na swoim laptopie. Jeśli wybierane przez Ciebie pole zniknie, codegen pada właśnie tam - a to najwcześniejszy moment, w którym ktokolwiek spoza cmssy może się o tym dowiedzieć.

Przypnij SDK i aktualizuj świadomie. Nie chroni to przed zmianami schematu, ale sprawia, że zachowanie samego klienta nie rusza się jednocześnie pod Tobą.