Semantik versiya

Semantic Versioning (SemVer) - versiya nömrəsinin dəyişikliklərin xarakterini necə əks etdirdiyinə dair müqavilə. Format: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - Uyğunsuz dəyişikliklər (breaking).
• MINOR - əks-uyumlu fiş/uzantılar.
• PATCH - əks-uyğun səhv/təhlükəsizlik düzəlişləri.

Məqsəd: API-nin, hadisələrin, məlumat sxemlərinin, SDK-ların və konfiqurasiyaların gözlənilən təkamülü.

1) Nömrələrin konvensiyası

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

Pre-release ('-alpha', '-beta', '-rc') - qeyri-sabit yığımlar; uyğunluq vəd etmir.
Build metadata ('+ sha') - müqayisə qaydasına təsir etmir, izləmə üçün faydalıdır.
1 qədər. 0. 0 hər hansı bir dəyişiklik breaking hesab edilə bilər (lakin əvvəldən qaydalara riayət etmək daha yaxşıdır).

2) Breaking/minor/patch saymaq üçün nə

• Kontrakt dəyişdirilmədən bug və təhlükəsizlik fiksləri.
• Müqaviləyə təsir etməyən Doc Update.
• Cavabları/hadisələri/sxemləri dəyişdirmədən optimallaşdırma.

• Yeni isteğe bağlı sahələrin/metodların/end nöqtələrinin əlavə edilməsi.
• İstehlakçılar naməlum dəyərlərə dözümlü olduqda enum dəyərlərinin genişləndirilməsi.
• Yeni DB indeksləri, nullable sütunları, köhnə əlavə yeni hadisələr.

• Sahələrin silinməsi/adının dəyişdirilməsi, növlərin dəyişdirilməsi, məcburiyyət.
• Semantika/status/səhv kodlarının dəyişdirilməsi.
• Serializasiya formatının, açar sxeminin, nəqliyyat protokolunun dəyişdirilməsi.
• Topiklərin sıxılması/birləşməsi, hadisənin mənasının köçürülməsi, partizan sxeminin dəyişdirilməsi.
• Əks uyğunluq olmadan «iki fazalı» keçid tələb edən BD miqrasiyası.

3) Artefaktlara görə versiyalaşdırma

3. 1 REST

Variantlar: 'URI/v1/...', başlıqlar ('Accept: application/vnd. acme. game+json; version = 1 '), parametr.
Tövsiyə: ictimai API üçün URI versiyası; daxili üçün - c negotiation başlığı vasitəsilə.
MINOR: isteğe bağlı sahələrin, yeni filtrlərin/resursların əlavə edilməsi; mövcud cavabları dəyişdirməyin.
PATCH: fiks, təsvirin dəqiqləşdirilməsi, sabit çeşidləmə.

3. 2 gRPC

MAJOR (yeni paket/xidmət: 'acme. wallet. v2`).
Yeni sahələr - optional işarəsi ilə; server naməlum görməməzlikdən gəlməlidir.
Sahələr silinmir: «deprikeyt + bir nömrə ayırın», silmək - yalnız növbəti MAJOR-da.

3. 3 GraphQL

MINOR: yeni sahələr/növləri/query; silinir - '@deprecated' + miqrasiya pəncərəsi vasitəsilə, tam silinir - MAJOR.
Dəyişmək nullable → qeyri-nullable - MAJOR.

3. 4 Hadisələr və Topiklər (Kafka/SQS)

Sxemlər Schema Registry: təkamül additive (defolt ilə sahələr əlavə).
Yeni uyğun olmayan versiya → yeni subject/topic ('bet. settled. v2`).
Partizan açarı MAJOR daxilində dəyişməz olaraq qalır.

3. 5 DB sxemləri

1. Sütun əlavə edin (nullable/c defolt) →

2. Arxanı doldurun →

3. Oxu tərcümə →

4. Köhnəni silin (yalnız MAJOR-da).

/ RK/unikallığının dəyişdirilməsi - MAJOR, ficheflag və ikiqat qeyd altında.

3. 6 SDK/CLI

İctimai metodlar/işarələr eyni qaydalardır.
Avtogenerasiya üçün (OpenAPI/Proto) - paket adı və artefaktların versiyası.

4) Deprikasiya siyasəti və həyat dövrü

Hər bir fasilə dəyişikliyindən əvvəl deprikasiya baş verir (adətən xarici üçün 90-180 gün, daxili üçün 30-60 gün).
Rabitə: changelog, e-mail/veb-hook partnyorları, geliştirici portalında banner.
Dual-run rejimi: paralel olaraq 'v1' və 'v2' saxlayırıq, trafikin payını 'v1' izləyirik.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Müştəri istədiyiniz + maksimum dəstəklənən versiyanı göndərir (məsələn, 'Accept-Version: 1,2').
Server 'Content-Version: 2' cavab verir.
İki yönlü protokollarda (WebSocket, gRPC) - 'supported _ versions' ilə Hello-frame mübadiləsi.

6) Provayder adapterləri ilə inteqrasiya (ACL)

Xarici provayder sxemi dəyişir - adapter daxilində v1/v2 mapperlərini saxlayırıq və domen müqaviləmizi saxlayaraq daxili hadisə üçün MINOR buraxırıq.
Xarici dəyişikliklər içəriyə girirsə - bu bizim domen hadisəsinin MAJOR və yeni subject.

7) Changelog və kommit işarələri

• `feat:...` → MINOR
• 'fix:... '/' chore', 'docs', 'perf' (müqaviləsiz) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' və ya 'BREAKING CHANGE:' bədən → MAJOR

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

8) Buraxılışların avtomatlaşdırılması

CI: sxem validatorları (OpenAPI/Protobuf/Avro/JSON-Schema), breaking-diff detekti.
SemVer-bot: Conventional Commits → analizi bump (major/minor/patch) hesablayır, etiket qoyur, generit changelog.
CD: ayrı deploy və release (fitness/konfiqlər yeni versiyanı aktivləşdirir).
Nəzarət: uğurlu canary və razılaşdırılmış SLO qədər PRO-da 'latest' dərc etmirik.

9) Konfiqurasiya və siyasət üçün semantika

Konfiqlərin də sxem versiyası var: 'schema _ version: 3'.
MINOR - yeni isteğe bağlı sahələr/qaydalar; MAJOR - strukturun/öhdəliyin dəyişdirilməsi.
Validatorda v2/v3 dəstəyi; uyğunsuzluq hesabatı ilə konfiqurasiya miqratoru.

10) Uyğunluq testi

Consumer-driven contract tests (Pact): hər inteqrasiya üçün.
Schema-evolution tests: yeni sxemdə köhnə payload 'və əksinə.
Replay: gölgədə 'v1' na 'v2' prod trafikini oynatmaq.
Property-based: naməlum sahələrə/enum müqavimət.

11) Versiyalara görə müşahidə

Ölçü/logları etiketləyin: 'api _ version', 'schema _ version', 'event _ version'.
Daşbordlar miqrasiyası: versiyalar üzrə trafik payı, səhv/gecikmə 'v1/v2'.
Alertlər: əgər 'v1' plan üzrə azalmasa; 'v2' buraxıldıqdan sonra 4xx/5xx artım.

12) Dayanmadan miqrasiya patternləri

Expand → Migrate → Contract (БД).
Dual write + oxu keçid əvvəl divergency müqayisə.
Sıralama/qaydalar üçün Shadow compare.
Tenant/regionlarda Canary; sürətli geri dönüş üçün feature flags.
Read-compat/Write-compat pəncərələri: yeni versiya köhnə məlumatları oxuyur, lakin yeni formatda yazır.

13) Anti-nümunələr

«Hər sahədə versiya» əvəzinə resurs/hadisə versiyası.
MINOR altında gizli fasilə dəyişiklikləri (məsələn, defolt dəyişikliyi).
Pəncərə və istehlak metrləri olmadan deprikate aradan qaldırılması.
«Əbədi v1»: Köhnə versiyaların çıxarılması planının olmaması → texniki borclar və zəifliklər.
Biznes versiyası və konteyner görüntü versiyası qarışdırılması.

14) Version siyasətinin çek siyahısı

• Versiya formatı və həqiqət mənbələri qeydə alınmışdır (Registry/Portal).
• Artefaktlar üzrə breaking-meyarlar siyahısı təsdiq edilmişdir (REST/gRPC/GraphQL/events/DB).
• Deprikasiya prosesi: vaxt, rabitə, sunset/banner, dual-run.
• Avtomatik diff-checker sxemləri və Conventional Commits.
• Dashboard istehlak versiyası və alert.
• Miqrasiya playbook (expand/migrate/contract, dual-write, shadow).
• Konfiqlər və SDK öz versiyaları və registrləri var.
• Müştərilər üçün «versiyanı necə seçmək» və komandalar üçün «necə artırmaq» sənədləşdirilməsi.

15) Version nümunələri (iGaming-cases)

Hadisə 'BetSettled v1' → 'v2': əlavə 'void _ reason' (optional) və 'tax. amount` (optional) — MINOR. 'payout' → 'win _ amount' - MAJOR, yeni subject.
REST '/wallets/transfer ': əlavə filter'? tenant _ id = '- MINOR. Səhv kodu dəyişdirildi '409' → '422' - MAJOR.
GraphQL: 'Player. age 'kimi' @deprecated 'Player lehinə. ageGroup '- MINOR-da buraxılış, X dövründən sonra MAJOR-da çıxarılma.
BD: 'bonus _ wager _ left' nullable - MINOR sütunu əlavə edildi. Qeyri-null etdi və silindi 'bonus _ left' - MAJOR (expand/contract vasitəsilə).

Nəticə

Semantik versiyalaşdırma rəqəmlərlə deyil, etimad və proqnozlaşdırılabilirliklə bağlıdır. Aydın qaydalar, avtomatik yoxlamalar, nəzarət edilən deprikasiyalar və şəffaf telemetriya API-ni inkişaf etdirməyə imkan verir, inteqrasiya üçün ağrısız hadisələr və sxemlər - və dəyişiklikləri tez-tez, təhlükəsiz və mənalı şəkildə buraxın.