Семантикалык версиялоо

Semantic Versioning (SemVer) - версиянын номери өзгөрүүлөрдүн мүнөзүн кандай чагылдырары жөнүндө келишим. Формат: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - шайкеш келбеген өзгөрүүлөр (breaking).
• MINOR - карама-каршы Fich/узартуу.
• PATCH - тескери туура ката/коопсуздук.

Максаты: АПИнин алдын ала эволюциясы, окуялар, маалымат схемалары, SDK жана керектөөчүлөрдүн капыстан бузулушу жок конфигурациялар.

1) Сандар конвенциясы

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

Pre-release ('-alpha', '-beta', '-rc') - туруксуз түзүлүштөр; шайкештикти убада кылбайт.
Build metadata ('+ sha') - салыштыруу тартибине таасир этпейт, издөө үчүн пайдалуу.
1 чейин. 0. 0 ар кандай өзгөртүү breaking деп эсептелиши мүмкүн (бирок башынан эле эрежелерди сактоо жакшы).

2) Эмне breaking/minor/patch

• Келишим алмаштырылбастан, мүчүлүштүктөрдүн жана коопсуздуктун фикстери.
• Контрактка тиешеси жок док-апдейттер.
• Жоопторду/окуяларды/схемаларды өзгөртпөстөн оптималдаштыруу.

• Жаңы кошумча талааларды/ыкмаларды/эндпоинттерди кошуу.
• Эгерде керектөөчүлөр бейтааныш маанилерге чыдаса, энум маанилерин кеңейтүү.
• Жаңы DD индекстери, дефолт менен nullable колонкалар, эскиге кошумча жаңы окуялар.

• Талааларды алып салуу/атын өзгөртүү, түрлөрүн өзгөртүү, милдеттүүлүк.
• Семантиканы/статустарды/ката коддорун өзгөртүү.
• Сериалдаштыруу форматын, ачкыч схемасын, транспорт протоколун өзгөртүү.
• Топиктерди кысуу/бириктирүү, окуянын маанисин которуу, партиялаштыруу схемасын өзгөртүү.
• Кайра шайкештиги жок "эки фазалуу" которууну талап кылган БД миграциясы.

3) Артефакттар боюнча версиялоо

3. 1 REST

Параметрлери: 'URI/v1/...', аталыштары ('Accept: application/vnd. acme. game+json; version = 1 '), параметр.
Сунуш: коомдук API үчүн URI нускасы; ички үчүн - c negotiation аталышы аркылуу.
MINOR: кошумча талааларды, жаңы чыпкалар/ресурстарды кошуу; бар жоопторду өзгөртпөңүз.
PATCH: фикстер, сүрөттөлүштөрдү тактоо, туруктуу сорттоо.

3. 2 gRPC

→ MAJOR (жаңы пакети/кызматы: 'acme. wallet. v2`).
Жаңы талаалар - optional белгиси менен; Server белгисиз четке болушу керек.
Биз талааларды алып салбайбыз: "деприкейт + резервдик номер", алып салуу - кийинки MAJORда гана.

3. 3 GraphQL

MINOR: жаңы талаалар/түрлөрү/query; алып салуу - '@deprecated' + көчүрүү терезеси аркылуу, толук өчүрүү - MAJOR.
nullable → non-nullable өзгөртүү - MAJOR.

3. 4 Окуялар жана топиктер (Kafka/SQS)

Схемалар Schema Registry: эволюция additive (демейки менен талааларды кошуу).
Жаңы ылайыксыз версия → жаңы subject/topic ('bet. settled. v2`).
Партиялаштыруу ачкычы MAJOR ичинде өзгөрүүсүз турат.

3. 5 БД схемалары

1. Тилке кошуу (nullable/c дефолт) →

2. Толтуруу арткы →

3. Котормо окуу →

4. эски (гана MAJOR) алып салуу.

түрүн өзгөртүү/RK/уникалдуулугу - MAJOR, phicheflage жана кош жазуу астында.

3. 6 SDK/CLI

Коомдук ыкмалар/белгилер - ошол эле эрежелер.
Автогенерация үчүн (OpenAPI/Proto) - пакеттик аталыштын жана артефакттардын версиясы.

4) Деприкация саясаты жана жашоо цикли

Ар бир breaking-өзгөртүү деприкация алдында (адатта тышкы үчүн 90-180 күн, ички үчүн 30-60).
Байланыш: changelog, e-mail/webhook өнөктөштөр, баннерлер иштеп порталында.
dual-run режими: параллелдүү 'v1' жана 'v2' кармап, трафиктин үлүшүн 'v1' мониторинг.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Кардар каалаган нускасын + максималдуу колдоого жөнөтөт (мисалы, 'Accept-Version: 1,2').
Server жооп берет 'Content-Version: 2', эгерде көтөрө алган.
Эки тараптуу протоколдордо (WebSocket, gRPC) - 'supported _ versions' менен Hello-фреймдерди алмашуу.

6) Провайдерлердин адаптерлери менен интеграция (ACL)

Тышкы провайдер схеманы өзгөртөт - адаптердин ичинде v1/v2 мэпперлерин кармап, биздин домендик келишимди сактап, ички иш-чара үчүн MINOR чыгарабыз.
Эгерде тышкы өзгөрүүлөр ичине кирип кетсе, бул биздин домендик иш-чаранын MAJOR жана жаңы тема.

7) Changelog жана соода белгилери

• `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/Euro/JSON-Schema), breaking-diff detect.
SemVer-бот: Conventional Commits → талдоо bump (major/minor/patch) эсептеп, тег коюп, generit changelog.
CD: өзүнчө deploy жана release (phicheflags/конфиги жаңы нускасын иштетет).
Control: ийгиликтүү canary жана макулдашылган SLO чейин PRO 'latest' жарыялоо эмес.

9) Конфигурация жана саясат үчүн семантика

Config (YAML/JSON) да схема нускасы бар: 'schema _ version: 3'.
MINOR - жаңы кошумча талаалар/эрежелер; MAJOR - структураны/милдеттүүлүктү өзгөртүү.
validator v2/v3 колдоо; ылайыксыздык отчету менен конфигурациялардын мигратору.

10) шайкештик сыноо

Consumer-driven contract tests (Pact): ар бир бириктирүү үчүн.
Schema-evolution tests: жаңы схемасы боюнча эски payload's чуркап жана тескерисинче.
Replay: көлөкөдө 'v1' на 'v2' прод-трафигин ойнотуу.
Property-based: тааныш талаалар/enum каршылык.

11) Версиялар боюнча байкоо

Тегиздөө метрика/логи: 'api _ version', 'schema _ version', 'event _ version'.
Dashbord көчүрүү: версия боюнча трафиктин үлүшү, ката/жашыруун 'v1/v2'.
Алерт: эгерде 'v1' план боюнча төмөндөбөсө; 'v2' чыгарылгандан кийин 4xx/5xx өсүшү.

12) Миграциялык үлгүлөр токтоп калбастан

Expand → Migrate → Contract (БД).
Dual write + окуу которуу алдында айырмачылыктарды салыштыруу.
Рейтинг/эрежелер үчүн Shadow compare.
Тенанттар/региондор боюнча Canary; тез кайтаруу үчүн feature flags.
Read-compat/Write-compat терезелер: жаңы версия эски маалыматтарды окуп, бирок жаңы түрдө жазган.

13) Анти-үлгүлөрү

"Ар бир талаада Version" ордуна ресурсу/окуя чыгаруу.
MINOR астында жашыруун breaking-өзгөртүүлөр (мисалы, демейки өзгөртүү).
Терезесиз жана керектөө метрикалары жок өчүрүү.
"Түбөлүккө v1": Эски версияларды алып салуу планынын жоктугу → техникалык карыз жана алсыздыктар.
Бизнес версиясын жана контейнердик сүрөттүн версиясын аралаштыруу.

14) Версиялоо саясатынын чек тизмеси

• Жазылган версия жана чындык булактары (Каттоо/Портал).
• Артефакттар боюнча breaking-критерийлер тизмеси бекитилди (REST/gRPC/GraphQL/events/DB).
• Деприкация жараяны: мөөнөттөрү, байланыш, sunset/баннерлер, эки-жарыш.
• Автоматтык diff текшерүүчү схемалар жана Conventional Commits.
• Dashbord чыгаруу керектөө жана Алерт.
• көчүрүү Playbook (expand/migrate/contract, dual-write, shadow).
• Конфиги жана SDK өз нускасы жана реестри бар.
• кардарлар үчүн "нускасын тандоо үчүн кантип" документтештирүү жана команда үчүн "кантип жогорулатуу".

15) Версиялоо мисалдары (iGaming учурлары)

Окуя 'BetSettled v1' → 'v2': кошулду 'void _ reason' (optional) жана 'tax. amount` (optional) — MINOR. Кайра 'payout' → 'win _ amount' - MAJOR, жаңы subject.
REST '/wallets/transfer ': чыпкасы кошулду'? tenant _ id = '- MINOR. ката коду өзгөрдү '409' → '422' - MAJOR.
GraphQL: белгиленген 'Player. age 'катары' @deprecated 'пайдасына' Player. ageGroup '- MINORга чыгаруу, X мезгилинен кийин MAJORга алып салуу.
БД: "bonus _ wager _ left 'nullable - MINOR. non-null жана алынып салынды 'bonus _ left' - MAJOR (аркылуу expand/contract).

Корутунду

Семантикалык версиялоо цифралар жөнүндө эмес, ишеним жана алдын ала айтуу жөнүндө. Так эрежелер, автоматтык текшерүүлөр, контролдонуучу деприкациялар жана тунук телеметрия APIлерди өнүктүрүүгө мүмкүндүк берет, интеграция үчүн азабы жок окуялар жана схемалар - жана өзгөрүүлөрдү тез-тез, коопсуз жана маңыздуу чыгарат.