Semantik versiyalash

1) SemVer nima va nima uchun kerak

SemVer iste’molchilar yangilanishdan nimani kutishlari kerakligini tushunishlari uchun artefaktlar (kutubxonalar, API, servislar, sxemalar) ning taxminiy qoidalarini belgilaydi:

MAJOR - mos kelmaydigan oʻzgarishlar (breaking changes).
MINOR - yangi funksionallik, mos API.
PATCH - nuqsonlarni teskari-mos tuzatish.

Maqsad: shartnomalarning barqarorligi to’g "risida kelishib olish va yangilanishlar narxini pasaytirish.

2) Versiya formati

Baza formati:

`MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`

`1. 4. 7’- barqaror reliz.
`1. 5. 0-rc. 2’- pre-reliz (release candidate № 2).
`2. 0. 0+linux. arm64’- build-meta ma’lumotlar (versiyalarni taqqoslashga ta’sir qilmaydi).

Taqqoslash qoidalari:

1. Avval «MAJOR», so’ngra «MINOR», so’ngra «PATCH» solishtiriladi.

2. Pre-relizlar tegishli barqaror versiyadan kam:’1. 2. 0-rc. 1 < 1. 2. 0`.

3. Build-meta ma’lumotlar (’+...’) tartibga ta’sir qilmaydi:’1. 2. 0+001 == 1. 2. 0`.

3) Breaking change nima hisoblanadi

Breaking change - iste’molchining harakatlarini talab qiladigan har qanday o’zgarish:

Ommaviy usullar/endpointlar signaturasini olib tashlash/qayta nomlash/o’zgartirish.
Kirish/chiqish formatini oʻzgartirish (JSON sxemasi, turlari).
Xato kontraktlarini o’zgartirish (kodlar/tuzilmalar).
side-effects/SLAs oʻzgarishi (masalan, qatʼiy chegaralar yoki yangi majburiy maydonlar).

Breaking emas (to’g "ri amalga oshirilganda): ixtiyoriy maydonlarni qo’shish, enumni yangi qiymatlar bilan kengaytirish (agar mijoz ularni e’tiborsiz qoldirsa), yangi endpointlar, joriy chaqiruvlarga ta’sir qilmaydigan defoltli yangi bayroqlar.

4) Pre-relizlar va kanal strategiyalari

Pre-relizlar SemVer va’dalarini buzmasdan sinovdan o’tkazish imkonini beradi:

’alpha’,’beta’,’rc’belgilari. Misol:’2. 3. 0-beta. 3`.
Kanallar: nightly → alpha → beta → rc → stable.
Siyosat: pre-relizlar pre-relizlar uchun default bo’lgan tranzitiv bog’liqlik sifatida tushmasligi kerak.

5) Variantlar diapazonlari va qaramliklar aniqligi

Haqiqiy ekotizimlarda quyidagi diapazonlar ifodalaridan foydalaniladi:

5. 1 Node/npm (andoza SemVer)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0’(MINOR/PATCH ruxsat beradi, MAJOR belgilaydi).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0’(PATCHga MINOR doirasida ruxsat beradi).
`1. 4. x’- 1 dagi har qanday yamoq. 4.
Aniq pin:’1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0’- aniq chegaralar.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0)’- shu jumladan/faqat.
Prod-kritik artefaktlar uchun qattiq tepish tavsiya etiladi.

5. 4 Go modules

Har doim’vMAJOR’taglari toʻliq. MINOR. PATCH’;’v2 +’modul qoʻshimchasini talab qiladi ’/v2’.

Tavsiya: ilovalar uchun - aniq pinlar (reproducible builds). Kutubxonalar uchun - caret-diapazonlar (yangilanishlarni sinishsiz osonlashtirish).

6) CHANGELOG и Conventional Commits

Tuzatilgan oʻzgarishlar jurnali shaffoflikni oshiradi.

Conventional Commits:


feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.
Undov belgisi yoki’BREAKING CHANGE’bloki MAJOR oshirilishini eʼlon qiladi.
CHANGELOG kommitlar tarixidan (release-notes botlar) hosil bo’ladi.

7) API uchun versiyalash siyosati

Ommaviy API: qattiq SemVer; breaking → MAJOR.
HTTP/REST: ’/v1/...’, ’/v2/...’yoki’Accept: application/vnd. org. service. v2+json`.
JSON sxemalari: minor kengaytmalar - yangi ixtiyoriy maydonlar; major - majburiy bo’lganlarni olib tashlash/o’zgartirish.
gRPC/Protobuf: yangi raqamlar bilan yangi maydonlarni qoʻshing; dala raqamlaridan qayta foydalanmang; o’chirish → deprecate, mavjud bo’lganlarni «sindirish» emas.

8) Ma’lumotlar va migratsiya sxemalari

DB migratsiyasi ilova versiyasi bilan sinxronlashtiriladi:’app @ 1. 8. 0’talab qiladi’schema @ 1. 8. x`.
Sxemani oʻzgartirish uchun - fazalar: expand (qoʻshish), migrate, contract (olib tashlash). Eski shartnomani olib tashlaganingizdagina uni MAJOR ga koʻtaring.
Koʻchirish paytida ikki marta yozishni/oʻqishni qoʻllab-quvvatlang.

9) Monorepo va mikroservislar

Multi-package: har bir paketning o’z’MAJOR’si. MINOR. PATCH`; relizlarning umumiy ildiz sikli faqat meta-artefaktlar uchun.

Strategiyalarni oʻzgartirish:

Independent versions (Lerna/Changesets) - izolyatsiyani kuchaytiradi.
Lock-step - aloqa osonroq, ammo yolg’on MAJORlar ko’proq.
Mikroservislar uchun shartnomalarni (OpenAPI/Protobuf) alohida versiya bilan belgilang:’contract @ 2. 1. 0’, xizmat unga amal qiladi.

10) CI/CDdagi relizlarni avtomatlashtirish

Conventional Commits asosidagi avtoulov versiyasi:

`fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

Artefaktlarning avtoteglari va imzosi:

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

CHANGELOG’ni yaratish, reliz-noutlarni nashr etish, GitOps-repoda qaramliklarni yangilash,’main’doimo oxirgi barqaror tagni koʻrsatishini tekshirish.

11) Deprivatsiya siyosati (deprecation policy)

E’lon: funktsiyani MINOR-relizda deprecated deb belgilang, EOL muddatini bering (masalan, 90 kun).
Kuzatish: user/tenant kontekstli eskirgan endpointlardan foydalanishni manzilga soling.
Olib tashlash: quyidagi MAJOR’da. Migratsiya yoʻlini hujjatlashtiring.

12) Namunalar va shablonlar

12. 1 SemVer validatsiyasining muntazam ifodasi

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 Taqqoslash misollari

`1. 2. 3` < `1. 10. 0’(MINOR taqqoslash).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Qaramlik siyosati (YAML misoli)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) Anti-patternlar

Prodda’latest ’/suzuvchi teglardan foydalanish.
Haqiqiy buzilishlarsiz MAJORni oshirish («marketing versiyasi»).
’PATCH’ nomi ostida yashirin breaking-oʻzgarishlar.
Pre-relizlar prod-ilovalarning tranzitiv qaramliklarida.
Artefaktni yangi tegsiz oʻzgartirish (mutabel versiyalar).
DB kodi va sxemasining kelishilmagan versiyalari.

14) Joriy etish chek-varaqasi (0-45 kun)

0-10 kun

SemVerni majburiy standart sifatida qabul qiling, sinish mezonlarini tasdiqlang.
Conventional Commits va PR namunasini’BREAKING CHANGE’maydoniga kiriting.

11-25 kun

Semantic-release/changesets, CHANGELOG avtogeneratsiyasiga ulaning.
Artefaktlarni’vX’tagiga yozib oling. Y.Z`.

26-45 kun

Eskirgan API ning deprecation policy va telemetriyasini kiriting.
Shartnomalar (OpenAPI/Proto) va servislar versiyalarini sinxronlashtiring.
’latest’ va siyosat darajasidagi noto’g’ri teglarni taqiqlang.

15) Etuklik metrikasi

Faqat SemVer yorlig’i bo’yicha nashr etiladigan artefaktlar%.
MINOR versiyalari orasidagi oʻrtacha migratsiya vaqti.
Yashirin breaking-oʻzgarishlar tufayli sodir boʻlgan hodisalar soni.
Repozitoriyalarda Conventional Commits qamrovi (> 95%).
Mahsulotda suzuvchi diapazonsiz qaramliklar ulushi (> 90%).

16) SemVer kerak bo’lmaganda

Tashqi iste’molchilarsiz ichki tezkor prototiplar (sanalangan versiyalash mos keladi).
Eksperimental figurali ma’lumotlar/modellar (konvertorlar darajasida mos keladigan Model/Schema Versioning yaxshiroq).
Barqaror ommaviy APIsiz kontent paketlari.

17) Xulosa

SemVer - bu ishlab chiqaruvchi va iste’molchi o’rtasidagi ishonch shartnomasi. Uyg’unlikni buzadigan narsalarni aniq belgilang, reliz turlarini aniqlash va artefaktlarni nashr etishni avtomatlashtiring, shaffof CHANGELOGni yuriting va deprivatsiya siyosatiga rioya qiling. SHunda yangilanishlar muntazam, prognoz qilinadigan va xavfsiz bo’ladi, infratuzilma va API esa biznes uchun shoksiz rivojlanadi.

Semantik versiyalash