Semantik versiyalash

Semantic Versioning (SemVer) - versiya raqami o’zgarishlar xususiyatini qanday aks ettirishi to’g "risidagi shartnoma. Formati: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - mos kelmaydigan oʻzgarishlar (breaking).
• MINOR - teskari mos keladigan chichlar/kengaytmalar.
• PATCH - xato/xavfsizlikni teskari moslashuvchi tuzatishlar.

Maqsad: iste’molchilar to’satdan buzilmasdan API, voqealar, ma’lumotlar sxemalari, SDK va konfiguratsiyalarning oldindan aytib bo’ladigan evolyutsiyasi.

1) Raqamlar konvensiyasi

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

Pre-release (’-alpha’,’-beta’,’-rc’) - beqaror yig’ilishlar; mos kelmaydi.
Build metadata (’+ sha’) - taqqoslash tartibiga ta’sir qilmaydi, izlash uchun foydalidir.
1 gacha. 0. 0 har qanday o’zgarishni breaking deb hisoblash mumkin (lekin qoidalarga boshidanoq rioya qilish yaxshiroqdir).

2) Breaking/minor/patch ni nima deb hisoblash kerak

• Kontraktni o’zgartirmasdan xatolar va xavfsizlik fikslari.
• Kontraktga ta’sir qilmaydigan dok-apdeytlar.
• Javoblarni/hodisalarni/sxemalarni oʻzgartirmasdan optimallashtirish.

• Yangi ixtiyoriy maydonlarni/usullarni/endpointlarni qoʻshish.
• Agar isteʼmolchilar notanish qiymatlarga chidamli boʻlsa, enum qiymatlarini kengaytirish.
• Yangi DB indekslari, nullable ustunlari, eskisiga qoʻshimcha yangi voqealar.

• Maydonlarni olib tashlash/qayta nomlash, turlarni, majburiyatlarni oʻzgartirish.
• Semantika/maqom/xato kodlarini oʻzgartirish.
• Seriallashtirish formatini, kalitlar sxemasini, transport protokolini o’zgartirish.
• Topiklarning siqilishi/qo’shilishi, hodisaning mazmunini o’zgartirish, partiyalashtirish sxemasini o’zgartirish.
• «Ikki fazali» almashtirishni talab qiladigan BD migratsiyasi.

3) Artefaktlar bo’yicha versiyalash

3. 1 REST

Variantlar:’URI/v1/...’, sarlavhalar (’Accept: application/vnd. acme. game+json; version = 1’), parametr.
Tavsiya: ommaviy API uchun URI versiyasi; ichki uchun - c negotiation sarlavhasi orqali.
MINOR: ixtiyoriy maydonlarni, yangi filtrlar/resurslarni qoʻshish; mavjud javoblarni o’zgartirmang.
PATCH: fikslar, tavsiflarni aniqlashtirish, barqaror saralash.

3. 2 gRPC

Signatur/turlarni oʻzgartirish → MAJOR (yangi paket/xizmat:’acme. wallet. v2`).
Yangi maydonlar - optional belgisi bilan; server nomaʼlum narsalarni eʼtiborsiz qoldirishi kerak.
Maydonlarni olib tashlamaymiz: «deprikeyt + raqamni zaxira qilish», olib tashlash - faqat quyidagi MAJORda.

3. 3 GraphQL

MINOR: Yangi maydonlar/tiplar/query; olib tashlash -’@deprecated’+ migratsiya oynasi orqali, to’liq olib tashlash - MAJOR.
Oʻzgartirish nullable → non-nullable - MAJOR.

3. 4 Voqealar va topiklar (Kafka/SQS)

Sxemalar Schema Registry: evolyutsiya additive (defoltli maydonlarni qoʻshish).
Yangi mos kelmaydigan versiya → yangi subject/topic (’bet. settled. v2`).
Partiyalash kaliti MAJOR ichida oʻzgarmagan.

3. 5. BQ sxemalari

1. Ustunni qoʻshish (nullable/c defolt) →

2. Orqa oynani toʻldirish →

3. Oʻqishni tarjima qilish →

4. Eskisini olib tashlash (faqat MAJORda).

/ RK/noyoblik turini oʻzgartirish - MAJOR, ficheflag va qoʻshaloq yozuv ostida.

3. 6 SDK/CLI

Ommaviy usullar/signatura - xuddi shunday qoidalar.
Avtogeneratsiya uchun (OpenAPI/Proto) - paket nomi va artefaktlarning versiyasi.

4) Deprikatsiyalar siyosati va hayot sikli

Har bir breaking-o’zgarishdan oldin deprikatsiya sodir bo’ladi (odatda tashqi uchun 90-180 kun, ichki uchun 30-60 kun).
Kommunikatsiyalar: changelog, e-mail/vebxuklar hamkorlarga, bannerlar ishlab chiquvchi portalida.
Dual-run rejimi: parallel ravishda’v1’va’v2’tutamiz,’v1’trafik ulushini kuzatamiz.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Mijoz istalgan + maksimal qoʻllab-quvvatlanadigan versiyani yuboradi (masalan,’Accept-Version: 1,2’).
Server’Content-Version: 2’ga javob beradi.
Ikki yo’nalishli protokollarda (WebSocket, gRPC) -’supported _ versions’bilan Hello-frame almashinuvi.

6) Provayder adapterlari bilan integratsiya (ACL)

Tashqi provayder sxemani o’zgartiradi - adapter ichida biz v1/v2 mapperlarini saqlaymiz va domen shartnomamizni saqlab qolgan holda ichki voqea uchun MINOR chiqaramiz.
Agar tashqi oʻzgarishlar ichkariga kirsa, bu bizning domen hodisasining MAJOR va yangi subject.

7) Changelog va kommit belgilari

• `feat:...` → MINOR
• ’fix:... ’/’ chore’,’docs’,’perf’(shartnomasiz) → PATCH
• ’feat!: ’/’ fix!: ’/’ refactor!:’ yoki’BREAKING CHANGE:’tanada → MAJOR

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

8) Relizlarni avtomatlashtirish

CI: sxemalar validatorlari (OpenAPI/Protobuf/Euro/JSON-Schema), breaking-difflar detekti.
SemVer-bot: Conventional Commits → analizi bump (major/minor/patch) ni hisoblab chiqadi, tag qo’yadi, generit changelog.
CD: alohida deploy va release (ficheflaglar/konfiglar yangi versiyani faollashtiradi).
Nazorat: Muvaffaqiyatli va kelishilgan SLOlargacha’latest’ni PROda e’lon qilmaymiz.

9) Konfiguratsiyalar va siyosatlar uchun semantika

Konfiglar (YAML/JSON) ham sxema versiyasiga ega:’schema _ version: 3’.
MINOR - yangi ixtiyoriy maydonlar/qoidalar; MAJOR - tuzilma/majburiyatni o’zgartirish.
Validatorda v2/v3 ni qo’llab-quvvatlash; konfiguratsiyalar migratori nomuvofiqliklar hisoboti bilan.

10) Muvofiqlikni sinash

Consumer-driven contract tests (Pact): har bir integratsiya uchun.
Schema-evolution tests: eski payload’larni yangi sxemada haydash va aksincha.
Replay: soyada’v1’ga’v2’prod-trafigini takrorlash.
Property-based: notanish maydonlarga chidamlilik/enum.

11) Versiyalar bo’yicha kuzatish

Metrik/loglarni belgilang:’api _ version’,’schema _ version’,’event _ version’.
Migratsiya dashbordlari: versiyalar bo’yicha trafik ulushi, xatolik/yashirin’v1/v2’bo’yicha.
Alertlar: agar’v1’reja bo’yicha pasaymasa; ’v2’ chiqarilgandan keyin 4xx/5xx o’sishi.

12) Migratsiya patternlari

Expand → Migrate → Contract (БД).
Dual write + oʻqishni oʻzgartirishdan oldin divergentlarni taqqoslash.
Rang/qoidalar uchun shadow compare.
tenantlar/mintaqalar bo’yicha Canary; tez qaytish uchun feature flags.
Read-compat/Write-compat: yangi versiya eski ma’lumotlarni o’qiydi, lekin yangi formatda yozadi.

13) Anti-patternlar

Resurs/hodisani versiyalash oʻrniga «Har bir maydondagi versiya».
MINOR ostida yashirin breaking-oʻzgarishlar (masalan, defoltlarni oʻzgartirish).
Derazasiz va isteʼmol metriksiz deprikeytni olib tashlash.
«Abadiy v1»: eski versiyalarni olib tashlash rejasi yo’qligi → texnik qarz va zaifliklar.
Konteyner tasvirining biznes versiyasi va versiyasini aralashtirish.

14) Versiyalash siyosatining chek-varaqasi

• Versiyalar formati va haqiqat manbalari qayd etildi (Registry/Portal).
• Artefaktlar bo’yicha breaking-mezonlar ro’yxati tasdiqlandi (REST/gRPC/GraphQL/events/DB).
• Deprikatsiya jarayoni: muddatlar, kommunikatsiyalar, sunset/bannerlar, dual-run.
• Sxemalar va Conventional Commits avtomatik diff-checker.
• Dashbord isteʼmol versiyasi va alertlar.
• Migratsiya pleybuklari (expand/migrate/contract, dual-write, shadow).
• Konfigi va SDK o’z versiyalari va registrlariga ega.
• Mijozlar uchun «qanday variantni tanlash» va buyruqlar uchun «qanday oshirish» hujjatlari.

15) Versiyalash namunalari (iGaming-keyslar)

’BetSettled v1’ →’v2’hodisasi:’void _ reason’(optional) va’tax. amount` (optional) — MINOR. Qayta nomlandi’payout’→’win _ amount’- MAJOR, yangi subject.
REST ’/wallets/transfer’:’? tenant _ id =’- MINOR filteri qoʻshilgan. Xato kodi oʻzgartirildi’409’→’422’- MAJOR.
GraphQL:’Player. age’@deprecated’sifatida’Player’foydasiga. ageGroup’- MINORga chiqarish, MAJORga X. davridan keyin olib tashlash.
BD:’bonus _ wager _ left’nullable - MINOR ustunini qo’shing. Non-null va’bonus _ left’- MAJOR (expand/contract orqali) olib tashlandi.

Xulosa

Semantik versiyalash raqamlar haqida emas, balki ishonch va bashorat qilish haqida. Aniq qoidalar, avtomatik tekshiruvlar, nazorat qilinadigan deprikatsiyalar va shaffof telemetriya APIlarni, integratsiya uchun og’riqsiz voqealar va sxemalarni rivojlantirishga va tez-tez, xavfsiz va mazmunli o’zgarishlarni chiqarishga imkon beradi.