Версияи семантикӣ

Versioning Semantic (Semver) - шартнома дар бораи он, ки рақами версия хусусияти тағиротро чӣ гуна инъикос мекунад. Формат: MAJOR. МИНОР. ПАТЧ [-PRERELEASE] [+ BUILD].

• MAJOR - Тағйироти номувофиқ (шикастан).
• MINOR - хусусиятҳо/васеъшавии мутақобила.
• PATCH - Хатогиҳои мувофиқ ба қафо/ислоҳи амният.

Ҳадаф: таҳаввулоти пешгӯишавандаи API, рӯйдодҳо, схемаҳои маълумот, SDK ва конфигуратсияҳо бидуни тақсимоти ногаҳонии истеъмолкунандагон.

1) Рақамҳои конвенсия

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

Нашри пешакӣ ('-alpha', '-beta', '-rc') - маҷлисҳои ноустувор; мутобиқатро ваъда надиҳед.
Сохтани метамаълумот ('+ sha') - ба тартиби муқоиса таъсир намерасонад, ки барои пайгирӣ муфид аст.
То 1. 0. 0 Ҳама гуна тағиротро шикастан мумкин аст (аммо беҳтар аст, ки қоидаҳоро аз аввал риоя кунед).

2) Чиро бояд баррасӣ кард/minor/patch

• Ислоҳи хатогиҳо ва амният бидуни тағир додани шартнома.
• Навсозиҳои docking, ки ба шартнома таъсир намерасонанд.
• Оптимизатсия бидуни тағир додани посухҳо/рӯйдодҳо/схемаҳо.

• Илова кардани майдонҳо/усулҳо/нуқтаҳои нав.
• Васеъ кардани арзишҳои энум, агар истеъмолкунандагон арзишҳои ношиносро таҳаммул кунанд.
• Индексҳои нави пойгоҳи додаҳо, сутунҳои беэътибор бо нобаёнӣ, рӯйдодҳои нав ба ғайр аз кӯҳна.

• Нест кардан/тағир додани майдонҳо, тағир додани намудҳо, ҳатмӣ.
• Тағйир додани семантика/статус/рамзҳои хато.
• Тағир додани формати сериализатсия, нақшаи калидӣ, протоколи нақлиёт.
• Мавзӯъҳоро фишурда/якҷоя кунед, маънои ҳодисаро интиқол диҳед, схемаи тақсимотро тағир диҳед.
• Муҳоҷирати пойгоҳи додаҳо, ки гузариши "ду марҳила" -ро бидуни мутобиқати қафо талаб мекунанд.

3) Тарҷумаи артифакт

3. 1 ИСТИРОҲАТ

Вариантҳо: 'URI/v1/...', сарлавҳаҳо ('Қабул: ариза/внд. акме. бозӣ + json; версия = 1 '), параметр.
Тавсия: версия дар URI барои API-ҳои оммавӣ; барои дохилӣ - тавассути сарлавҳаи c гуфтушунид.
MINOR: илова кардани майдонҳои ихтиёрӣ, филтрҳо/захираҳои нав; ҷавобҳои мавҷударо тағйир надиҳед.
ПАТЧ: ислоҳ, такмили таъриф, навъбандии устувор.

3. 2 GRPC

Тағйир додани MAJOR → имзоҳо/намудҳо (бастаи нав/хидмат: 'acme. ҳамён. v2 ').
Майдонҳои нав - ихтиёрӣ нишон дода шудаанд; сервер бояд номаълумро нодида гирад.
Мо майдонҳоро нест намекунем: "depricket + рақамро захира кунед", нест кунед - танҳо дар MAJOR навбатӣ.

3. 3 Диаграммаи QL

MINOR: майдонҳои нав/намудҳо/дархостҳо; хориҷ кардан - тавассути '@ deprecated' + равзанаи муҳоҷират, пурра бартараф кардан - MAJOR.
Тағйир додани nullable ғайри-nullable - MAJOR.

3. 4 Чорабиниҳо ва мавзӯъҳо (Кафка/SQS)

Схемаҳо дар Феҳристи схема: эволютсияи иловагиҳо (майдонҳоро бо пешфарз илова кунед).
Нусхаи нави номувофиқ → мавзӯъ/мавзӯи нав ('бет. ҳал шудааст). v2 ').
Калиди тақсимкунӣ дар MAJOR тағйирнопазир аст.

3. 5 диаграммаҳои DB

1. Илова кардани сутун (nullable/default) →

2. Пур кардани backfill

3. Translate → Хондан

4. Тоза кардани кӯҳна (танҳо MAJOR).

Навъи тағирот/PK/беҳамтоӣ - MAJOR, дар зери phicheflag ва вурудоти дугона.

3. 6 SDK/CLI

Усулҳо/имзоҳои ҷамъиятӣ ҳамон қоидаҳоянд.
Барои автогенератсия (OpEN API/Proto) - нусхаи номи партия ва артефактҳо.

4) Сиёсати маҳрумшавӣ ва давраи зиндагӣ

Ҳар як тағироти шикаста пеш аз депрессия (одатан 90-180 рӯз барои беруна, 30-60 барои дохилӣ).
Алоқа: changelog, почтаи электронӣ/webhooks ба шарикон, баннерҳо дар портали таҳиякунанда.
Ҳолати дугона: 'v1' ва 'v2' -ро мувозӣ нигоҳ доред, ҳиссаи трафики 'v1' -ро назорат кунед.
Сарлавҳаҳои ғуруби офтоб (REST): 'Ғуруби офтоб: 2026-03-31', 'Пайванд: <url>; rel = "фарсудашавӣ" '.

5) Музокироти версия

Мизоҷ версияи дилхоҳ + версияи ҳадди аксарро дастгирӣ мекунад (масалан, 'Қабул-Версия: 1,2').
Сервер бо 'Content-Version: 2' if метавонад мусоидат кунад.

Дар протоколҳои дуҷониба (Web

6) Интегратсияи адаптерҳои провайдер (ACL)

Провайдери беруна схемаро тағир медиҳад - дар дохили адаптер мо харитасозони v1/v2-ро нигоҳ медорем ва MINOR-ро барои ҳодисаи дохилӣ нигоҳ медорем ва шартномаи домени худро нигоҳ медорем.
Агар тағироти беруна ба дохили худ ворид шаванд, ин MAJOR чорабинии домени мо ва мавзӯи нав аст.

7) Changelog ва тамғакоғазҳо содир кунед

• 'feat:...' → MINOR
• 'ислоҳ:... '/' chore ',' docs ',' perf '(шартнома нест) → PATCH
• 'feat!: '/' ислоҳ кунед!: '/' refactor!:' ё 'Тағйироти BREAKING:' дар 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: валидаторҳои ноҳиявӣ (OpEN API/Protobuf/Avro/JSON-Schema), ошкоркунии вайроншавӣ. бештар

Semver-bot: таҳлили фармонҳои анъанавӣ → ҳисобкуниро ҳисоб мекунад (major/minor/patch), теги мегузорад, тағиротро ба вуҷуд меорад.
CD: ҷойгиркунӣ ва нашри алоҳида (phicheflags/конфигуратсияҳо версияи навро фаъол мекунанд).
Назорат: то PRO-и муваффақ ва SLO-ҳои мувофиқашуда "навтарин" -ро дар PRO нашр накунед.

9) Семантика барои конфигуратсияҳо ва сиёсатҳо

Конфигуратсияҳо (YAML/JSON) инчунин версияи схема доранд: 'schema _ version: 3'.
MINOR - майдонҳои/қоидаҳои нави ихтиёрӣ MAJOR - тағйири сохтор/ӯҳдадорӣ.
дастгирии v2/v3 дар validator; муҳоҷирро бо гузориши номутобиқатӣ ошно кунед.

10) Санҷиши мутобиқат

Санҷишҳои шартномавӣ аз ҷониби истеъмолкунандагон (Паймон): барои ҳамгироӣ.
Санҷишҳои схема-эволютсия: сарбории кӯҳнаро дар схемаи нав иҷро кунед ва баръакс.
Бозсозӣ - Трафики истеҳсолии 'v1' -ро ба 'v2' дар соя мебозад.
Ба амвол асос ёфтааст: муқовимат ба майдонҳои ношинос/enum.

11) Мушоҳида аз рӯи версия

Нишондиҳандаҳо/гузоришҳои теги: 'api _ version', 'schema _ version', 'event _ version'.
Панелҳои муҳоҷират: ҳиссаи трафик аз рӯи версияҳо, хатогӣ/таъхир аз ҷониби 'v1/v2'.
Огоҳиҳо: агар 'v1' мувофиқи нақша ба поён нарасад; Афзоиши 4xx/5xx пас аз баромади 'v2'.

12) Шакли муҳоҷират бидуни вақти корӣ

Тавсеаи → Муҳоҷират → Шартнома (BD).
Навиштани дугона + фарқиятҳоро пеш аз иваз кардани хониш муқоиса кунед.
Соя барои рейтинг/қоидаҳо муқоиса кунед.
Канария аз ҷониби иҷорагир/минтақа; парчамҳои хусусият барои ғалтаки зуд.
Тирезаҳои хондан-compat/Write-compat: версияи нав маълумоти кӯҳнаро мехонад, аммо дар формати нав менависад.

13) Анти-намунаҳо

"Версия дар ҳар як соҳа" ба ҷои тағир додани манбаъ/ҳодиса.
Тағироти шикастани пинҳонӣ дар зери MINOR (масалан, тағир додани пешфарз).
Бартараф кардани ченакҳои бидуни тиреза ва истеъмол.
"Forever v1": ҳеҷ нақшае барои аз байн бурдани версияҳои кӯҳнаи қарзи техникӣ ва осебпазирӣ нест.
Версияи бизнес ва версияи тасвири контейнерро омехта кунед.

14) Рӯйхати санҷиши сиёсати Version

• Формати собит ва манбаъҳои ҳақиқат (Феҳрист/Портал).
• Рӯйхати тасдиқшудаи меъёрҳои шикастани артефактҳо (REST/g
• Раванди ихроҷ: вақт, иртибот, ғуруби офтоб/баннерҳо, дугона.
• Санҷиши худкори diff ва ӯҳдадориҳои анъанавӣ.
• Панели панели истеъмолӣ ва ҳушдордиҳӣ.
• Китобҳои бозии муҳоҷират (васеъ/муҳоҷират/шартнома, навиштани дугона, соя).
• Конфигуратсияҳо ва SDK-ҳо версияҳо ва парвандаҳои худро доранд.
• Ҳуҷҷатгузорӣ "чӣ гуна интихоб кардани версия" барои муштариён ва "чӣ гуна такмил додан" барои гурӯҳҳо.

15) Намунаҳои версия (парвандаҳои бозӣ)

'Betsoled v1' event → 'v2': илова 'void _ reason' (ихтиёрӣ) ва 'андоз. маблағи '(ихтиёрӣ) - MINOR. Номи 'пардохт' → 'win _ found' - MAJOR, мавзӯи нав.
REST '/ҳамёнҳо/интиқол ': филтри иловашуда'? иҷорагир _ id = '- MINOR. Рамзи хатои тағирёфтаи '409' → '422' - MAJOR.
GraphQL: ишора шудааст 'Player. синну сол 'ҳамчун' @ deprecated 'ба манфиати' Player. age 'Group' - озод кардан дар MINOR, нест кардан дар MAJOR пас аз давраи X.
DB: сутуни иловашудаи 'bonus _ wager _ left' беэътибор - MINOR. 'Bonus _ left' сохта ва нест карда шудааст - MAJOR (тавассути тавсеа/шартнома).

Хулоса

Версияи семантикӣ на дар бораи рақамҳо, балки дар бораи эътимод ва пешгӯишаванда аст. Қоидаҳои возеҳ, санҷишҳои автоматӣ, деприцияҳои назоратшаванда ва телеметрияи шаффоф ба API, рӯйдодҳо ва схемаҳои бидуни дард имкон медиҳанд, ки барои ҳамгироӣ таҳаввул ёбанд ва тағиротро зуд-зуд, бехатар ва пурмаъно раҳо кунанд.