Wersioning semantyczny

Semantic Versioning (SemVer) - umowa o tym, jak numer wersji odzwierciedla charakter zmian. Format: MAJOR. DROBNE. PLASTER [-PRERELEASE] [+ BUILD].

• MAJOR - Niezgodne ze wspólnym rynkiem zmiany (złamanie).
• MINOR - wzajemnie kompatybilne funkcje/rozszerzenia.
• PATCH - Wsteczne kompatybilne poprawki błędów/zabezpieczeń.

Cel: przewidywalna ewolucja interfejsów API, zdarzeń, schematów danych, SDK i konfiguracji bez nagłych awarii konsumenckich.

1) Numery konwencji

X.Y.Z[-alpha.1    -rc.1][+build.sha]

Pre-release ('-alpha', '-beta', '-rc') - niestabilne zespoły; nie obiecuj kompatybilności.
Build metadane ('+ sha') - nie ma wpływu na kolejność porównania, przydatne do śledzenia.
Do 1. 0. 0 Wszelkie zmiany można uznać za złamanie (ale lepiej przestrzegać zasad od samego początku).

2) Co rozważyć breaking/minor/patch

• Poprawki do błędów i zabezpieczeń bez zmiany umowy.
• Aktualizacje dokowania, które nie wpływają na kontrakt.
• Optymalizacja bez zmiany odpowiedzi/zdarzeń/schematów.

• Dodaj nowe opcjonalne pola/metody/punkty końcowe.
• Rozszerzenie wartości enum, jeśli konsumenci tolerują nieznane wartości.
• Nowe indeksy bazy danych, nieważne kolumny z domyślnymi, nowe zdarzenia oprócz starych.

• Usuwanie/zmienianie nazwy pól, zmiany typów, obowiązkowe.
• Zmień kody semantyczne/statusy/błędy.
• Zmiana formatu serializacji, schemat klucza, protokół transportowy.
• Skompresuj/połączyć tematy, przenieść znaczenie zdarzenia, zmienić schemat podziału.
• Migracje baz danych, które wymagają „dwufazowego” przełączania bez kompatybilności wstecznej.

3) Artefakt wersioning

3. 1 ODPOCZYNEK

Warianty: 'URI/v1/...', nagłówki ('Accept: application/vnd. acme. gra + json; wersja = 1 '), parametr.
Zalecenie: wersja URI dla publicznych API; dla wewnętrznych - poprzez nagłówek c negocjacji.
MINOR: dodać opcjonalne pola, nowe filtry/zasoby; nie zmieniaj istniejących odpowiedzi.
Poprawki, dopracowanie definicji, stabilne sortowanie.

3. 2 gRPC

Zmiana GŁÓWNYCH → podpisów/typów (nowy pakiet/usługa: 'acme. portfel. v2 ").
Nowe pola - oznaczone opcjonalnie; serwer musi ignorować nieznane.
Nie usuwamy pól: „depricket + reserve a number”, usuń - tylko w następnym MAJOR.

3. 3 GraphQL

MINOR: nowe pola/typy/zapytania; usunięcie - poprzez '@ deprecated' + okno migracji, pełne usunięcie - MAJOR.
Zmiana nullable → non -nullable - MAJOR.

3. 4 Wydarzenia i tematy (Kafka/SQS)

Schematy w rejestrze schematów: ewolucja dodatku (dodaj pola z domyślnymi).
Nowa wersja niezgodna → nowy temat/temat ('bet. rozstrzygnięty. v2 ").
Klucz podziału jest niezmienny w MAJOR.

3. Schematy 5 DB

1. Dodaj kolumnę (nieważną/domyślną) →

2. Wypełnić zasypkę →

3. Przetłumacz → odczyty

4. Usuń stare (tylko MAJOR).

Zmiana typu/PK/uniqueness - MAJOR, pod ficheflagiem i podwójnym wpisem.

3. 6 SDK/PBL

Publiczne metody/podpisy to te same zasady.
Do autogeneracji (OpenAPI/Proto) - wersja nazwy partii i artefaktów.

4) Polityka deprywacji i cykl życia

Każda zmiana łamania poprzedzona jest deprymacją (zwykle 90-180 dni dla zewnętrznych, 30-60 dla wewnętrznych).
Komunikacja: changelog, e-mail/webhooks do partnerów, banery w portalu deweloperskim.
Tryb podwójnego jazdy: równolegle przechowywać 'v1' i 'v2', monitorować udział ruchu 'v1'.
Nagłówki zachodu słońca (REST): 'Zachód słońca: 2026-03-31', 'Link: <url>; rel = „deprecation” '.

5) Negocjacje wersji

Klient wysyła żądaną wersję + maksymalną obsługiwaną wersję (na przykład „Accept-Version: 1,2”).
Serwer odpowiada za pomocą 'Content-Version: 2ng-if może promować.
W protokołach dwukierunkowych (WebSocket, gRPC) - wymiana ramek Hello z 'supported _ versions'.

6) Integracja adaptera dostawcy (ACL)

Zewnętrzny dostawca zmienia system - wewnątrz adaptera przechowujemy mapery v1/v2 i uwalniamy MINOR do zdarzenia wewnętrznego, zachowując naszą umowę domeny.
Jeśli zmiany zewnętrzne wprowadzają się do środka, jest to MAJOR naszego wydarzenia domeny i nowy temat.

7) Znaczniki Changelog i commit

• „wyczyn:...” → MAŁY
• "naprawić:... '/' chore ',' docs', 'perf' (bez umowy) → PATCH
• „feat!” :/„ fix! ”:/„ refactor!” lub „BREAKING CHANGE:” in MAJOR → body

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) Automatyzacja zwolnienia

CI: walidatory obwodów (OpenAPI/Protobuf/Avro/JSON-Schema), wykrywanie rozproszone. więcej

SemVer-bot: analiza Konwencjonalne Commits → oblicza bump (major/minor/patch), umieszcza znacznik, generuje changelog.
CD: oddzielne wdrożenie i zwolnienie (phicheflags/configs aktywować nową wersję).
Kontrola: nie publikować „najnowszych” na PRO, aż do sukcesu kanaryjskiego i uzgodnionych SLO.

9) Semantyka dla konfiguracji i polityk

Konfiguracje (YAML/JSON) mają również wersję schematu: 'schema _ version: 3'.
MINOR - nowe fakultatywne pola/zasady MAJOR - zmiana struktury/obowiązku.
wsparcie v2/v3 w walidatorze; konfig migrant z raportem niezgodności.

10) Badanie zgodności

Testy umów konsumenckich (pakt): na integrację.
Schemat-testy ewolucji: uruchom stare ładunki na nowym schemacie i odwrotnie.
Replay - Gra ruch produkcyjny 'v1' do 'v2' w cieniu.
Nieruchomości: odporność na nieznane pola/enum.

11) Obserwowalność według wersji

Tag metrics/logs: 'api _ version', 'schema _ version', 'event _ version'.
Deski rozdzielcze migracji: udział ruchu według wersji, błąd/opóźnienie przez 'v1/v2'.
Wpisy: jeśli 'v1' nie pójdzie w dół zgodnie z planem; Wzrost 4xx/5xx po zwolnieniu 'v2'.

12) Wzory migracji bez przestojów

Rozszerzenie → Migrate → Kontrakt (М, ").
Dual write + porównaj rozbieżności przed przełączeniem odczytu.
Porównaj cień dla rankingu/zasad.
Kanaryjski według najemcy/regionu; posiadają flagi do szybkich wałków.
Okna Read-compat/Write-compat: nowa wersja czyta stare dane, ale pisze w nowym formacie.

13) Anty-wzory

„Wersja w każdym polu” zamiast wersji zasobu/zdarzenia.
Ukryte zmiany łamania w ramach programu MINOR (na przykład zmiana domyślnych wartości).
Usuwanie pozbawionych bez okien i mierników zużycia.
„Forever v1”: brak planu usunięcia starych wersji → długów technicznych i luk.
Wymieszaj wersję biznesową i wersję obrazu kontenera.

14) Lista kontrolna zasad weryfikacji

• Stały format wersji i źródła prawdy (Rejestr/Portal).
• Zatwierdzony wykaz kryteriów łamania według artefaktów (REST/gRPC/GraphQL/events/DB).
• Proces deprymacji: czas, komunikacja, zachód słońca/banery, podwójny bieg.
• Automatyczny kontroler różnic i konwencjonalne Commits.
• Deski rozdzielcze do wersji i zużycia alarmu.
• Playbooks migracji (rozszerzenie/migracja/umowa, podwójne pisanie, cień).
• Konfiguracje i SDK mają własne wersje i przypadek.
• Dokumentacja „jak wybrać wersję” dla klientów i „jak uaktualnić” dla zespołów.

15) Przykłady wersji (przypadki iGaming)

"BetSettled v1 'event →' v2 ': dodano' nieważny _ powód '(nieobowiązkowo) i' podatek. kwota "(opcjonalnie) - MINOR. Zmieniono nazwę na 'wypłata' → 'win _ amount' - MAJOR, nowy temat.
REST '/portfele/transfer ': dodany filtr'? lokator _ id = '- MINOR. Zmieniono kod błędu '409' → '422' - MAJOR.
GraphQL: oznaczony 'Player. wiek 'jako' @ deprecated 'na korzyść' Player '. † Group '- wydanie w MINOR, usunięcie w MAJOR po okresie X.
DB: dodana kolumna 'bonus _ wager _ left' nieważna - MINOR. Wykonane non-null i usunięte 'bonus _ left' - MAJOR (poprzez expand/contract).

Wniosek

Wersioning semantyczny nie dotyczy liczb, ale zaufania i przewidywalności. Jasne zasady, zautomatyzowane kontrole, kontrolowane niedostatki i przezroczysta telemetria pozwalają API, zdarzenia i schematy wolne od bólu ewoluować dla integracji - i uwalniać zmiany często, bezpiecznie i sensownie.