Semantik wersiýa

Semantic Versioning (SemVer) - wersiýanyň belgisiniň üýtgemeleriň häsiýetini nädip görkezýändigi baradaky şertnama. Format: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - gabat gelmeýän üýtgeşmeler (breaking).
• MINOR - ters gabat gelýän çyzyklar/giňelmeler.
• PATCH - ters gabat gelýän ýalňyşlyk/howpsuzlyk düzedişleri.

Maksat: sarp edijileriň duýdansyz döwülmezden API, wakalaryň, maglumat shemalarynyň, SDK we konfigurasiýalaryň öňünden aýdylýan ewolýusiýasy.

1) Nomerler konwensiýasy

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

Pre-release ('-alpha', '-beta', '-rc') - durnuksyz gurnamalar; gabat geljekdigini wada bermeýärler.
Build metadata ('+ sha') - deňeşdirme tertibine täsir etmeýär, yzarlamak üçin peýdalydyr.
1-e çenli. 0. 0 Islendik üýtgeşme breaking hasap edilip bilner (ýöne başyndan bäri düzgünleri berjaý etmek has gowudyr).

2) Näme hasaplamaly breaking/minor/patch

• Kontrakt çalşylmazdan baglaryň we howpsuzlygyň fiksleri.
• Şertnama täsir etmeýän doklar.
• Jogaplary/wakalary/shemalary üýtgetmezden optimizirlemek.

• Täze goşmaça meýdanlary/usullary/endpointleri goşmak.
• Sarp edijiler nätanyş gymmatlyklara çydamly bolsa, enum gymmatlyklary bilen giňeltmek.
• Täze DB indeksleri, defolt bilen nullable sütünleri, köne ýagdaýlara goşmaça täze wakalar.

• Meýdanlary aýyrmak/adyny üýtgetmek, görnüşleri, borçlylygy üýtgetmek.
• Semantikany/statuslary/ýalňyşlyk kodlaryny üýtgetmek.
• Serial görnüşiniň, açar shemasynyň, ulag teswirnamasynyň üýtgemegi.
• Topikleri gysmak/birleşdirmek, wakanyň manysyny geçirmek, partiýa ýerleşdiriş shemasyny üýtgetmek.
• Tersine gabat gelmezden "iki fazaly" geçmegi talap edýän DB göçmeleri.

3) Artefaktlar boýunça wersiýalaşdyrmak

3. 1 REST

Wariantlar: 'URI/v1/...', sözbaşylar ('Accept: application/vnd. acme. game+json; version = 1 '), parametr.
Teklip: köpçülige açyk API üçin URI-de wersiýa; içerki üçin - c negotiation sözbaşy arkaly.
MINOR: goşmaça meýdanlary, täze süzgüçleri/çeşmeleri goşmak; bar bolan jogaplary üýtgetmäň.
PATCH: fiksler, düşündirişleri takyklamak, durnukly sortlamak.

3. 2 gRPC

Belgileriň/görnüşleriň üýtgemegi → MAJOR (täze paket/hyzmat: 'acme. wallet. v2`).
Täze meýdanlar - optional bellikli; serwer näbelli zatlary äsgermezlik etmeli.
Meýdanlary aýyrmaýarys: "deprikate + rezerve belgisi", aýyrmak - diňe indiki MAJOR-da.

3. 3 GraphQL

MINOR: Täze meýdanlar/görnüşler/query; aýyrmak - '@deprecated' arkaly göçmek penjiresi, doly aýyrmak - MAJOR.
Üýtgetmek nullable → non-nullable - MAJOR.

3. 4 Wakalar we topikler (Kafka/SQS)

Shema registriýasyndaky shemalar: additive ewolýusiýasy (defoltly meýdanlary goşmak).
Täze gabat gelmeýän wersiýa → täze subject/topic ('bet. settled. v2`).
Partiýanyň açary MAJOR-yň içinde üýtgemeýär.

3. 5 DB shemalary

1. Sütün goşmak (nullable/c defolt) →

2. Belligi doldurmak →

3. Okamalary terjime et →

4. Köne (diňe MAJOR)

/ RK/özboluşlylygynyň üýtgemegi - MAJOR, fiçeflag we goşa ýazgy astynda.

3. 6 SDK/CLI

Jemgyýetçilik usullary/belgileri - şol bir düzgünler.
Awtogenerasiýa üçin (OpenAPI/Proto) - bukjanyň adynyň we artefaktlarynyň görnüşi.

4) Deprikasiýa syýasaty we durmuş aýlawy

Her bir arakesmäniň üýtgemeginden öň deprikasiýa bolýar (adatça daşarky günler üçin 90-180 gün, içerki günler üçin 30-60 gün).
Aragatnaşyklar: changelog, e-mail/webhuklar hyzmatdaşlara, bannerler döredijiniň portalynda.
Dual-run düzgüni: paralel 'v1' we 'v2' tutýarys, 'v1' traffiginiň paýyna gözegçilik edýäris.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Müşderi islenýän wersiýany + iň ýokary goldanýan wersiýany iberýär (mysal üçin, 'Accept-Version: 1,2').
Serwer 'Content-Version: 2' diýip jogap berýär.
Iki taraplaýyn teswirnamalarda (WebSocket, gRPC) - "supported _ versions" bilen Hello-frame alyş-çalşygy.

6) Üpjün edijileriň adapterleri bilen integrasiýa (ACL)

Daşarky üpjün ediji shemany üýtgedýär - adapteriň içinde v1/v2 mapperlerini saklaýarys we domen şertnamamyzy saklap, içerki waka üçin MINOR çykarýarys.
Daşarky üýtgeşmeler içeri girse - bu domen wakamyzyň MAJOR we täze subject.

7) Changelog we kommitleriň bellikleri

• `feat:...` → MINOR
• 'fix:... '/' chore', 'docs', 'perf' (şertnamasyz) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' veya 'BREAKING CHANGE:' bedende → MAJOR

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

8) Relizleri awtomatlaşdyrmak

CI: shema tassyklaýjylary (OpenAPI/Protobuf/Euro/JSON-Shema), breaking-diffs detekti.
SemVer-bot: Conventional Commits → analizi bump (major/minor/patch) hasaplaýar, tagt goýýar, generit changelog.
CD: aýry deploy we release (ficheflagy/konfigi täze wersiýany işjeňleşdirýär).
Gözegçilik: üstünlikli canary we ylalaşylan SLO-lara çenli 'latest' PRO-da çap etmeýäris.

9) Konfigurasiýa we syýasat üçin semantika

Konfigiler (YAML/JSON) hem shemanyň wersiýasyna eýe: 'schema _ version: 3'.
MINOR - täze goşmaça meýdanlar/düzgünler; MAJOR - gurluşyň/borçnamanyň üýtgemegi.
Walidatorda v2/v3 goldawy; gabat gelmezlik hasabaty bilen konfigurasiýa migratory.

10) Laýyklygy barlamak

Consumer-driven contract tests (Pact): her integrasiýa üçin.
Schema-evolution tests: Köne payloadlaryň täze shemada geçmegi we tersine.
Replay: 'v1' -a 'v2' -ni kölegede çalmak.
Property-based: nätanyş meýdanlara çydamlylyk/enum.

11) Wersiýalar boýunça syn edilmegi

Metrikleri/loglary belläň: 'api _ version', 'schema _ version', 'event _ version'.
Göçmegiň daşbordlary: wersiýalar boýunça traffigiň paýy, ýalňyşlyk/gizlinlik 'v1/v2'.
Alertler: eger 'v1' meýilnama boýunça azalmasa; 'v2' çykarylandan soň 4xx/5xx beýikligi.

12) Duralgasyz migrasiýa patternleri

Expand → Migrate → Contract (БД).
Dual write + okamadan öň deňsizligi deňeşdirmek.
Reýting/düzgünler üçin shadow compare.
Tenantlar/sebitler boýunça Kanary; çalt yza gaýdyp gelmek üçin feature flags.
Oka-compat/Write-compat penjireleri: täze wersiýa köne maglumatlary okaýar, ýöne täze formatda ýazýar.

13) Anti-patternler

Çeşmäni/wakany wersiýalaşdyrmagyň ýerine "Her meýdanda wersiýa".
MINOR-yň aşagyndaky gizlin breaking-üýtgeşmeler (mysal üçin defoltlary üýtgetmek).
Penjiresiz we sarp ediş metriksiz aýyrmak.
"Hemişelik v1": köne wersiýalary aýyrmak meýilnamasynyň ýoklugy → tehniki karz we gowşaklyk.
Konteýner şekiliniň iş wersiýasyny we wersiýasyny garyşdyrmak.

14) Wersiýalaşdyrmak syýasatynyň çek-sanawy

• Wersiýalaryň formaty we hakykat çeşmeleri hasaba alyndy (Registry/Portal).
• Artefaktlar boýunça breaking-kriteriýalaryň sanawy tassyklandy (REST/gRPC/GraphQL/events/DB).
• Deprikasiýa prosesi: möhletler, aragatnaşyklar, sunset/bannerler, dual-run.
• Awtomatiki diff-barlag shemalary we Conventional Commits.
• Wersiýalary we alertleri sarp etmek üçin daşbordlar.
• Göçmegiň pleýbuklary (expand/migrate/contract, dual-write, shadow).
• Konfigi we SDK-nyň öz wersiýalary we registrleri bar.
• Müşderiler üçin "wersiýasyny nädip saýlamalydygy" we toparlar üçin "nädip ýokarlandyrmalydygy".

15) Wersiýalaşdyrmagyň mysallary (iGaming-wakalar)

Waka 'BetSettled v1' → 'v2': 'void _ reason' (optional) we 'tax. amount` (optional) — MINOR. 'payout' → 'win _ amount' - MAJOR, täze subject.
REST '/wallets/transfer ': süzgüç goşduk'? tenant _ id = '- MINOR. Hata kody üýtgedildi '409' → '422' - MAJOR.
GraphQL: 'Player bellendi. age '@deprecated' Player '-iň peýdasyna. ageGroup '- MINOR-a goýbermek, MAJOR-a aýyrmak X.
BD: 'bonus _ wager _ left' nullable - MINOR sütünini goşduk. Null etmedik we 'bonus _ left' - MAJOR-y aýyrdyk (expand/contract arkaly).

Netije

Semantiki wersiýalaşdyrmak sanlar hakda däl-de, ynam we öňünden aýdylmak hakda. Anyk düzgünler, awtomatiki barlaglar, gözegçilik edilýän deprikasiýalar we aç-açan telemetriýa API-leriň, wakalaryň we shemalaryň integrasiýa üçin agyrysyz ösmegine we üýtgeşmeleri ýygy-ýygydan, howpsuz we manyly goýbermäge mümkinçilik berýär.