Semantik versiya

Semantik versiya

1) SemVer nədir və niyə lazımdır

• MAJOR - Uyğunsuz dəyişikliklər (breaking changes).
• MINOR - API uyğun yeni funksionallıq.
• PATCH - geri qaytarıla bilən qüsurların düzəldilməsi.

Məqsəd: müqavilələrin sabitliyi barədə razılığa gəlmək və yeniləmələrin dəyərini azaltmaqdır.

2) Versiya formatı

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

`1. 4. 7 '- sabit buraxılış.
`1. 5. 0-rc. 2 '- pre-release (release candidate № 2).
`2. 0. 0+linux. arm64 '- build-metadata (versiyaların müqayisəsinə təsir göstərmir).

1. Əvvəlcə «MAJOR», sonra «MINOR», sonra «PATCH» müqayisə olunur.

2. Pre-relizlər müvafiq sabit versiyadan daha azdır: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Build-metadata ('+...') sıraya təsir etmir: '1. 2. 0+001 == 1. 2. 0`.

3) Breaking change hesab olunur

• İctimai metodların/end nöqtələrinin silinməsi/adının dəyişdirilməsi/işarəsinin dəyişdirilməsi.
• Giriş/çıxış formatının dəyişdirilməsi (JSON sxemi, növləri).
• Səhv müqavilələrinin dəyişdirilməsi (kodlar/strukturlar).
• Side-effects/SLA-ların dəyişdirilməsi (məsələn, ciddi limitlər və ya yeni məcburi sahələr).

Breaking deyil (düzgün həyata keçirildikdə): isteğe bağlı sahələrin əlavə edilməsi, yeni dəyərlərlə enum genişləndirilməsi (müştəri onlara məhəl qoymasa), yeni son nöqtələr, cari çağırışlara təsir etməyən defoltlarla yeni bayraqlar.

4) Pre-relizlər və kanal strategiyaları

• Etiketlər: 'alpha', 'beta', 'rc'. Nümunə: '2. 3. 0-beta. 3`.
• Kanallar: nightly → alpha → beta → rc → stable.
• Siyasət: pre-relizlər default məhsullar üçün transitiv asılılıq kimi daxil olmamalıdır.

5) Variant diapazonları və asılılıq dəqiqliyi

5. 1 Node/npm (SemVer default)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(MINOR/PATCH, MAJOR fiksasiya edir).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(MINOR daxilində PATCH imkan verir).
`1. 4. x '- 1-də hər hansı bir yamaq. 4.
Dəqiq pin: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- açıq sərhədlər.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- daxil/müstəsna.
Prod-kritik artefaktlar üçün ciddi təpik tövsiyə olunur.

5. 4 Go modules

Həmişə tam etiketlər 'vMAJOR. MINOR. PATCH ';' v2 + 'modulu '/v2' şəkilçisini tələb edir.

Tövsiyə: tətbiqlər üçün - dəqiq pinlər (reproducible builds). Kitabxanalar üçün - caret diapazonları (yeniləmələri sındırmadan asanlaşdırmaq).

6) CHANGELOG и Conventional Commits

Strukturlaşdırılmış dəyişiklik jurnalı şəffaflığı artırır.

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` и т. д.
Nida işarəsi və ya 'BREAKING CHANGE' bloku MAJOR artımını elan edir.
CHANGELOG kommitlərin tarixindən (release-notes botları) yaranır.

7) API üçün versiya siyasəti

Public API: ciddi SemVer; breaking → MAJOR.
HTTP/REST: URL versiyası/başlığı: '/v1/... ', '/v2/...' və ya 'Accept: application/vnd. org. service. v2+json`.
JSON sxemləri: minor genişləndirmələr - yeni isteğe bağlı sahələr; major - məcburi çıxarılması/dəyişdirilməsi.
gRPC/Protobuf: yeni nömrələrlə yeni sahələr əlavə edin; sahə nömrələrini yenidən istifadə etməyin; → deprecate aradan qaldırılması, mövcud deyil «qırmaq».

8) Məlumat və miqrasiya sxemləri

DB miqrasiyaları tətbiqin versiyaları ilə sinxronlaşdırılır: 'app @ 1. 8. 0 'tələb edir' schema @ 1. 8. x`.
Sxem dəyişikliyi üçün - fazalar: expand (əlavə et), migrate, contract (sil). Versiyanı yalnız köhnə müqaviləni sildiyiniz zaman MAJOR-a qaldırın.
Miqrasiya zamanı ikiqat yazma/oxumağı dəstəkləyin.

9) Monorepo və mikroservislər

Multi-package: Hər paketin öz 'MAJOR. MINOR. PATCH`; yalnız meta-artefaktlar üçün ümumi kök reliz dövrü.

• Independent versions (Lerna/Changesets) - izolyasiyanı gücləndirir.
• Lock-step - daha asan ünsiyyət, lakin daha çox saxta MAJOR.
• Mikroservislər üçün ayrı bir versiya ilə müqavilələri (OpenAPI/Protobuf) qeyd edin: 'contract @ 2. 1. 0 ', xidmət onu izləyir.

10) CI/CD-də buraxılışların avtomatlaşdırılması

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

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 Generation, Release Nouts, GitOps-Repo-da asılılığı yeniləmək, 'main' həmişə son sabit etiketi göstərir.

11) Deprivasiya siyasəti (deprecation policy)

Elan: funksionallığı MINOR-relizində deprecated kimi qeyd edin, EOL müddətini verin (məsələn, 90 gün).
Müşahidə: user/tenant kontekstində köhnəlmiş end nöqtələrinin istifadəsini loqo edin.
Silinir: Aşağıdakı MAJOR. Miqrasiya yolunu sənədləşdirin.

12) Nümunələr və şablonlar

12. 1 Müntəzəm SemVer validasiya ifadəsi

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 Müqayisə nümunələri

`1. 2. 3` < `1. 10. 0 '(MINOR ilə müqayisə).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Asılılıq siyasəti (YAML nümunəsi)

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-nümunələr

Prodda 'latest '/üzən etiketlərdən istifadə edin.
Real pozulmadan MAJOR-un artırılması («marketinq versiyaları»).
'PATCH' adı altında gizli breaking dəyişikliklər.
Pre-relizlər transitiv asılılıq prod-applications.
Yeni etiketsiz artefaktı dəyişdirin (mutabel versiyalar).
Kod və DB sxeminin razılaşdırılmamış versiyaları.

14) Giriş çek siyahısı (0-45 gün)

0-10 gün

SemVer-i məcburi standart kimi qəbul edin, qırılma meyarlarını təsdiq edin.
Conventional Commits və 'BREAKING CHANGE' sahəsi ilə PR şablonunu daxil edin.

11-25 gün

semantic-release/changesets, CHANGELOG avtomatik generasiya qoşun.
Imzanı və artefaktların vX etiketi ilə yayımlanmasını konfiqurasiya edin. Y.Z`.

26-45 gün

Köhnə API istifadə deprecation policy və telemetriya daxil edin.
Müqavilələrin (OpenAPI/Proto) və xidmətlərin versiyalarını sinxronlaşdırın.
Siyasət səviyyəsində 'latest' və mutable etiketləri qadağan edin (ORA/CI qaydaları).

15) Yetkinlik metrikası

Yalnız SemVer etiketi ilə nəşr olunan artefaktların% -i.
MINOR versiyaları arasında orta miqrasiya müddəti.
Gizli fasilə dəyişikliklərinə görə hadisələrin sayı.
Anbarlarda Conventional Commits əhatə (> 95%).
Məhsulda üzən diapazonlar olmadan asılılığın payı (> 90%).

16) SemVer lazım deyil zaman

Xarici istehlakçılar olmadan daxili sürətli prototiplər (tarixi versiyalaşdırma uyğun gəlir).
Data/eksperimental modellər (daha yaxşı Model/Schema Versioning konverter səviyyəsində uyğunluğu ilə).
Sabit ictimai API olmadan məzmun paketləri.

17) Nəticə

SemVer istehsalçı və istehlakçı arasında etimad müqaviləsidir. Uyğunluğu pozan şeyi dəqiq müəyyənləşdirin, buraxılış növlərinin tanınmasını və artefaktların yayımlanmasını avtomatlaşdırın, şəffaf CHANGELOG aparın və deprivasiya siyasətinə əməl edin. Sonra yeniləmələr rutin, proqnozlaşdırıla bilən və təhlükəsiz olacaq - və infrastruktur və API-lər biznes şoku olmadan inkişaf edəcək.