სემანტიკური ვერსია

Semantic Versioning (SemVer) - ხელშეკრულება იმის შესახებ, თუ როგორ ასახავს ვერსიის ნომერი ცვლილებების ბუნებას. ფორმატი: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - შეუთავსებელი ცვლილებები.
• MINOR - საპირისპირო ფიჩები/გაფართოება.
• PATCH - შეცდომების/უსაფრთხოების საპირისპირო კორექტირება.

მიზანი: API- ს პროგნოზირებადი ევოლუცია, მოვლენები, მონაცემთა სქემები, SDK და კონფიგურაცია მომხმარებელთა უეცარი ავარიის გარეშე.

1) ნომრების კონვენცია

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

Pre-release ('-alpha', '-beta', '-rc') - არასტაბილური შეკრებები; არ გვპირდებიან თავსებადობას.
Build metadata ('+ sha') - არ მოქმედებს შედარების პროცედურაზე, სასარგებლოა ტრეკისთვის.
1-მდე. 0. ნებისმიერი ცვლილება შეიძლება ჩაითვალოს breaking (მაგრამ უმჯობესია დაიცვან წესები თავიდანვე).

2) რა ითვლება breaking/minor/patch

• შეცდომებისა და უსაფრთხოების ფიქსიები ხელშეკრულების შეცვლის გარეშე.
• Doc apdates, რომლებიც გავლენას არ ახდენენ ხელშეკრულებაზე.
• ოპტიმიზაცია პასუხების/მოვლენების/სქემების შეცვლის გარეშე.

• ახალი არჩევითი ველების/მეთოდების/ენდოინტების დამატება.
• Enum- ის გაფართოება მნიშვნელობებით, თუ მომხმარებლები მოუთმენლად ელიან უცნობ მნიშვნელობებს.
• ახალი BD ინდექსები, nullable სვეტები ნაგულისხმევი, ახალი მოვლენები ძველების გარდა.

• ველების მოცილება/შეცვლა, ტიპების შეცვლა, სავალდებულო.
• სემანტიკის/სტატუსის/შეცდომების კოდების შეცვლა.
• სერიალიზაციის ფორმატის შეცვლა, გასაღების სქემები, ტრანსპორტის პროტოკოლი.
• ტოპიკების შეკუმშვა/შერწყმა, მოვლენის მნიშვნელობის გადაცემა, გარიგების სქემის შეცვლა.
• მონაცემთა ბაზის მიგრაცია, რომელიც მოითხოვს „ორფაზიან“ გადართვას საპირისპირო თავსებადობის გარეშე.

3) არტეფაქტების ვერსია

3. 1 REST

პარამეტრები: 'URI/v1/...', სათაურები ('Accept: განაცხადი/vnd. acme. game+json; version = 1 '), პარამეტრი.
რეკომენდაცია: URI ვერსია საჯარო API- სთვის; შიდა - სათაურით negotiation.
MINOR: არჩევითი ველების, ახალი ფილტრების/რესურსების დამატება; არ შეცვალოთ არსებული პასუხები.
PATCH: ფიქსიები, აღწერილობების დახვეწა, სტაბილური დახარისხება.

3. 2 gRPC

ხელმოწერების/ტიპების შეცვლა MAJOR (ახალი პაკეტი/მომსახურება: 'acme. wallet. v2`).
ახალი ველები - ეტიკეტით optional; სერვერმა უნდა უგულებელყოს უცნობი.
ჩვენ ვერ ვიშორებთ მინდვრებს: „depricate + დაიცავით ნომერი“, წაშლა - მხოლოდ შემდეგ MAJOR- ში.

3. 3 GraphQL

MINOR: ახალი ველები/ტიპები/query; მოცილება - '@ deprecated' + მიგრაციის ფანჯრის მეშვეობით, სრული მოცილება - MAJOR.
არაკომერციული - არაკომერციული - MAJOR.

3. 4 მოვლენები და ტოპიკა (Kafka/SQS)

სქემები Schema Registry- ში: additive ევოლუცია (დაამატეთ ველები ნაგულისხმევი).
ახალი შეუთავსებელი ვერსია არის ახალი subject/topic ('bet. settled. v2`).
განაწილების გასაღები უცვლელია MAJOR- ის შიგნით.

3. 5 DD სქემები

1. დაამატეთ სვეტი (nullable/ერთად ნაგულისხმევი)

2. შეავსეთ ზურგჩანთა

3. კითხვის თარგმნა

4. ამოიღეთ ძველი (მხოლოდ MAJOR- ში).

ტიპის/RK/უნიკალურობის ცვლილება - MAJOR, ფიჩფლაგის ქვეშ და ორმაგი ჩანაწერი.

3. 6 SDK/CLI

საჯარო მეთოდები/ხელმოწერები - იგივე წესები.
ავტო წარმოებისთვის (OpenAPI/Proto) - პაკეტის სახელისა და არტეფაქტების ვერსია.

4) დეკრიმინალიზაციის პოლიტიკა და სასიცოცხლო ციკლი

თითოეულ breaking ცვლილებას წინ უძღვის დეკრიმინალიზაცია (ჩვეულებრივ, გარეგნობისთვის 90-180 დღე, შიდა 30-60).
კომუნიკაციები: changelog, el-mail/webhuks პარტნიორები, ბანერები დეველოპერის პორტალში.
ორმაგი რეჟიმში: პარალელურად ჩვენ ვატარებთ 'v1' და 'v2', ვაკვირდებით 'v1' ტრაფიკის წილს.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

კლიენტი აგზავნის სასურველ ვერსიას + მაქსიმალური მხარდაჭერილი (მაგალითად, 'Accept-Version: 1.2').
სერვერი პასუხობს 'შინაარსის ვერსიას: 2', თუ მას შეეძლო გაზრდა.
ორმხრივ ოქმებში (WebSocket, gRPC) - Hello ჩარჩოების გაცვლა „მხარდაჭერილი _ ვერსიებით“.

6) ინტეგრაცია პროვაიდერების ადაპტერებთან (ACL)

გარე პროვაიდერი ცვლის სქემას - ადაპტერის შიგნით, ჩვენ ვატარებთ mappers v1/v2 და ვაძლევთ MINOR- ს შიდა მოვლენისთვის, ინახავს ჩვენს დომენის კონტრაქტს.
თუ გარე ცვლილებები იშლება შიგნით, ეს არის ჩვენი დომენის ღონისძიების MAJOR და ახალი ქვეგრაფი.

7) Changelog და Commites ეტიკეტები

• `feat:...` → MINOR
• 'fix:... '/' chore', 'docs', 'perf' (ხელშეკრულების გარეშე )/PATCH
• 'feat!: '/' fix!: '/' refactor!:' ან 'BREAKING CHANGE:' სხეულში MAJOR

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

8) გამოშვების ავტომატიზაცია

CI: სქემების შემსრულებლები (OpenAPI/Protobuf/Avro/JSON-Schema), breaking დიფების დეტალი.
SemVer-bot: Conventional Commits- ის ანალიზი - ითვლის bump- ს (major/minor/patch), ათავსებს ჭდეებს, წარმოქმნის changelog.
CD: ცალკეული deploy და release (ficheflagies/კონფისკაცია ააქტიურებს ახალ ვერსიას).
კონტროლი: ჩვენ არ ვაქვეყნებთ 'latest- ს PRO- ს წარმატებულ კანარამდე და შეთანხმებულ SLO- სთან.

9) კონფიგურაციის სემანტიკა და პოლიტიკოსი

კონფიგურაციებს (YAML/JSON) ასევე აქვთ სქემის ვერსია: 'schema _ version: 3'.
MINOR - ახალი არჩევითი ველები/წესები; MAJOR - სტრუქტურის/სავალდებულო ცვლილება.
V2/v3 მხარდაჭერა მოვალეობის შემსრულებელში; ჩამორთმევის მიგრანტი შეუთავსებლობის ანგარიშით.

10) თავსებადობის ტესტირება

Consumer-driven კონტრაქტები: თითოეული ინტეგრაციისთვის.
Schema-evolution tests: ძველი payload- ის გაშვება ახალ სქემაზე და პირიქით.
Replay: სარეკლამო ტრაფიკის რეპროდუქცია 'v1' on 'v2' ჩრდილში.
Property-based: უცნობი მინდვრების წინააღმდეგობა/enum.

11) დაკვირვება ვერსიით

დააკვირდით მეტრიკებს/ლოგებს: 'app_ version', 'schema _ version', 'event _ version'.
მიგრაციის დაშბორდები: ტრეფიკის წილი ვერსიით, შეცდომა/ლატენტობა 'v1/v2'.
ალერტა: თუ 'v1' არ მცირდება გეგმის მიხედვით; სიმაღლე 4xx/5xx გამოშვების შემდეგ 'v2'.

12) მიგრაციის ნიმუშები

Expand → Migrate → Contract (БД).
Dual write + Divergents- ის შედარება კითხვის შეცვლამდე.
Shadow compare რანგის/წესებისთვის.
ჩრდილები/რეგიონები; feature flags სწრაფი დარტყმისთვის.
Read-compat/Write-compat ფანჯარა: ახალი ვერსია კითხულობს ძველ მონაცემებს, მაგრამ წერს ახალ ფორმატში.

13) ანტი შაბლონები

„ვერსია თითოეულ სფეროში“ რესურსის/ღონისძიების ვერსიის ნაცვლად.
ფარული breaking ცვლილებები MINOR- ის ქვეშ (მაგალითად, ნაგულისხმევი ცვლილება).
გამორთული ფანჯრის გარეშე და მოხმარების მეტრიკა.
„სამუდამოდ v1“: ძველი ვერსიების მოხსნის გეგმის არარსებობა სხვადასხვა დოლგებისა და დაუცველების შესახებ.
ბიზნეს ვერსიისა და კონტეინერის გამოსახულების ვერსიის ნაზავი.

14) ვერსიის პოლიტიკის სია

• დაფიქსირდა ვერსიების ფორმატი და ჭეშმარიტების წყაროები (რეგისტრი/პორტალი).
• დამტკიცდა არტეფაქტების კრიტერიუმების სია (REST/gRPC/GraphQL/events/DB).
• დეკრიმინალიზაციის პროცესი: ვადები, კომუნიკაცია, sunset/ბანერები, ორმაგი რუნი.
• ავტომატური diff ჩეკერი სქემები და Conventional Commits.
• დაშბორდები ვერსიისა და ალერტის მოხმარებისთვის.
• მიგრაციის playbows (expand/migrate/contract, ორმაგი write, shadow).
• კონფისკაციებს და SDK- ს აქვთ საკუთარი ვერსიები და რეესტრი.
• დოკუმენტაცია „როგორ ავირჩიოთ ვერსია“ მომხმარებლებისთვის და „როგორ გავზარდოთ“ გუნდებისთვის.

15) ვერსიების მაგალითები (iGaming შემთხვევები)

ღონისძიება 'BetSettled v1' v2 ': დაამატა' void _ reason '(optional) და' tax. amount` (optional) — MINOR. გადაკეთდა 'payout' '' win _ amount '- MAJOR, ახალი ქვეგრაფი.
REST '/wallets/transfer ': დაამატეთ ფილტრი'? tenant _ id = '- MINOR. შეცვალა შეცდომის კოდი '409' '' 422 '- MAJOR.
GraphQL: დაიმახსოვრე 'Player. age 'როგორც' @ deprecated '' 'Player- ის სასარგებლოდ. aGeGroup '- გამოშვება MINOR- ში, წაშლა MAJOR- ში X- ის შემდეგ.
BD: დაამატეთ სვეტი 'bonus _ wager _ left' nullable - MINOR. მათ გააკეთეს non-null და წაშალეს 'bonus _ left' - MAJOR (ექსპანსიის/კონტრაქტის საშუალებით).

დასკვნა

სემანტიკური ვერსია არ ეხება ციფრებს, არამედ ნდობასა და პროგნოზირებას. მკაფიო წესები, ავტომატური შემოწმებები, კონტროლირებადი დეფექტები და გამჭვირვალე ტელემეტრია საშუალებას გაძლევთ განვითარდოთ API, მოვლენები და სქემები ინტეგრაციისთვის ტკივილის გარეშე - და ხშირად, უსაფრთხო და მნიშვნელოვანი ცვლილებები გამოიტანოთ.