Semantik wersiýa

Semantiki wersiýa

1) SemVer näme we näme üçin zerur?

• MAJOR - gabat gelmeýän üýtgeşmeler (breaking changes).
• MINOR - API-e laýyk gelýän täze funksionallyk.
• PATCH - tersine-laýyk kemçilikleri düzetmek.

Maksat: şertnamalaryň durnuklylygy barada ylalaşmak we täzelenmeleriň bahasyny arzanlatmak.

2) Wersiýanyň görnüşi

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

`1. 4. 7 '- durnukly goýberiş.
`1. 5. 0-rc. 2 '- deslapky goýberiş (release candidate № 2).
`2. 0. 0+linux. arm64 '- build-meta-maglumatlar (wersiýalaryň deňeşdirilmegine täsir etmeýär).

1. Ilki 'MAJOR', soňra 'MINOR', soňra 'PATCH' deňeşdirilýär.

2. Pre-relizler degişli durnukly wersiýadan az: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Build-meta-maglumatlar ('...') tertibe täsir etmeýär: '1. 2. 0+001 == 1. 2. 0`.

3) Breaking change näme hasaplanýar

• Köpçüligiň usullarynyň/endpointleriniň belgisini aýyrmak/adyny üýtgetmek/üýtgetmek.
• Giriş/çykyş formatyny üýtgetmek (JSON-shema, görnüşleri).
• Ýalňyşlyk şertnamalarynyň üýtgemegi (kodlar/gurluşlar).
• Side-effects/SLAs üýtgetmek (mysal üçin, berk çäkler ýa-da täze hökmany meýdanlar).

Breaking däl (dogry durmuşa geçirilende): goşmaça meýdanlary goşmak, täze manylar bilen enum giňeltmek (eger müşderi olary äsgermezlik etse), täze endpointler, häzirki kynçylyklara täsir etmeýän defoltly täze baýdaklar.

4) Deslapky neşirler we kanal strategiýalary

• Bellikler: 'alpha', 'beta', 'rc'. Mysal: '2. 3. 0-beta. 3`.
• Kanallar: nightly → alpha → beta → rc → stable.
• Syýasat: pre-relizler proto-kolleksiýalar üçin wagtlaýyn garaşlylyk hökmünde düşmeli däldir.

5) Wersiýalaryň diapazony we garaşlylygyň takyklygy

5. 1 Node/npm (SemVer adaty)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(MINOR/PATCH rugsat berýär, MAJOR düzedýär).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(PATCH MINOR çäginde rugsat berýär).
`1. 4. x '- 1-de islendik ýama. 4.
Takyk pin: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- açyk serhetler.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- goşmak/diňe.
Prod-kritiki artefaktlar üçin berk urmak maslahat berilýär.

5. 4 Go modules

Elmydama doly taglar 'vMAJOR. MINOR. PATCH ';' v2 + 'modulyň goşulmasyny talap edýär '/v2'.

Maslahat: programmalar üçin - takyk pinler (reproducible builds). Kitaphanalar üçin - caret diapazonlary (täzelenmeleri bökdençsiz aňsatlaşdyrmak).

6) CHANGELOG и Conventional Commits

Gurluşlaşdyrylan üýtgeşmeler žurnaly aç-açanlygy ýokarlandyrýar.

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` и т. д.
"BREAKING CHANGE" ünlem belgisi ýa-da bloky MAJOR-yň ýokarlanandygyny yglan edýär.
CHANGELOG kommitleriň taryhyndan (release-notes botlar) emele gelýär.

7) API üçin wersiýa syýasaty

Jemgyýetçilik API-leri: berk SemVer; breaking → MAJOR.
HTTP/REST: URL wersiýasy/sözbaşy: '/v1/... ', '/v2/...' ýa-da 'Accept: application/vnd. org. service. v2+json`.
JSON-shemalar: kiçi giňelmeler - täze goşmaça meýdanlar; major - hökmany aýyrmak/üýtgetmek.
gRPC/Protobuf: täze sanlar bilen täze meýdanlary goşuň; meýdan belgilerini gaýtadan ulanmaň; Bar bolanlary "döwmek" däl-de, → deprecate aýyrmak.

8) Maglumatlaryň we migrasiýa shemalary

DB göçmeleri programmanyň wersiýalary bilen sinhronlaşdyrylýar: 'app @ 1. 8. 0 'talap edýär' schema @ 1. 8. x`.
Shemany üýtgetmek üçin - fazalar: expand (goşmak), migrate, contract (aýyrmak). Wersiýany diňe köne şertnamany aýyranyňyzda MAJOR-a çenli ýokarlandyryň.
Göçmek üçin goşa ýazga/okamaga goldaw beriň.

9) Monorepo we mikroservisler

Multi-package: her bukjanyň öz 'MAJOR. MINOR. PATCH`; relizleriň umumy kök sikli diňe meta-artefaktlar üçin.

• Independent versions (Lerna/Changesets) - izolýasiýany güýçlendirýär.
• Lock-step - has aňsat aragatnaşyk, ýöne ýalan MAJOR-lar.
• Mikroservisler üçin şertnamalary (OpenAPI/Protobuf) aýratyn wersiýasy bilen düzüň: 'contract @ 2. 1. 0 ', hyzmat oňa eýerýär.

10) CI/CD-de goýberilişi awtomatlaşdyrmak

• `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 nesli, goýberilen noutlary çap etmek, GitOps-repoda endikleri täzelemek, 'main' elmydama iň soňky durnukly belligi görkezýär.

11) Depriwasiýa syýasaty (deprecation policy)

Bildiriş: funksiýany MINOR-relizde deprecated diýip belläň, EOL möhletini bereliň (mysal üçin 90 gün).
Syn etmek: ulanyjy/tenant kontekstinde köne endpointleriň ulanylyşyny logika ediň.
Aýyrmak: indiki MAJOR-da. Göçmek ýoluny belläň.

12) Mysallar we şablonlar

12. 1 SemVer tassyklamasyny yzygiderli beýan etmek

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 Deňeşdirmeleriň mysallary

`1. 2. 3` < `1. 10. 0 '(MINOR bilen deňeşdirme).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Garaşlylyk syýasaty (YAML mysaly)

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-patternler

Prodda 'latest '/ýüzýän bellikleri ulanmak.
MAJOR-yň hakyky döwüksiz ýokarlanmagy ("marketing wersiýalary").
"PATCH" diýilýän gizlin breaking-üýtgeşmeler.
Pre-relizler prod-programmalaryň transitiw garaşlylygynda.
Täze tagsyz artefakty üýtget (üýtgeýän wersiýalar).
Kod we DB shemasynyň utgaşdyrylmadyk wersiýalary.

14) Giriş çek-sanawy (0-45 gün)

0-10 gün

SemVer-i hökmany standart hökmünde kabul ediň, kemçilik kriteriýalaryny tassyklaň.
Conventional Commits we 'BREAKING CHANGE' meýdany bilen PR şablonyny açyň.

11-25 gün

Semantic-release/changesets, CHANGELOG awtogenerasiýasyny birikdiriň.
Artefaktlaryň goluny we çap edilmegini "vX" tagyndan sazlaň. Y.Z`.

26-45 gün

Köne API-leri ulanmagyň deprecation policy we telemetriýasyny giriziň.
Şertnamalaryň (OpenAPI/Proto) we hyzmatlaryň wersiýalaryny sinhronlaşdyryň.
Syýasat derejesinde 'latest' we üýtgeýän bellikleri gadagan ediň (ORA/CI düzgünleri).

15) Kämillik ölçegleri

Diňe SemVer tagyndan neşir edilen artefaktlaryň% -i.
MINOR wersiýalarynyň arasynda göçmegiň ortaça wagty.
Gizlin breaking-üýtgeşmeler sebäpli ýüze çykan hadysalaryň sany.
Ammarlarda Conventional Commits örtügi (> 95%).
Önümde ýüzýän diapazonsyz endikleriň paýy (> 90%).

16) Haçan SemVer gerek däl

Daşarky sarp edijisiz içerki çalt prototipler (seneli wersiýalaşdyrmak amatly).
Synag şekilli maglumatlar/modeller (has gowusy konwerter derejesinde gabat gelýän Model/Schema Versioning).
Durnukly jemgyýetçilik API-si bolmadyk mazmun paketleri.

17) Netijenama

SemVer öndüriji bilen sarp edijiniň arasyndaky ynam şertnamasydyr. Laýyklygyň nämäni bozýandygyny anyk kesgitläň, relizleriň görnüşlerini tanamagy we artefaktlary çap etmegi awtomatlaşdyryň, aç-açan CHANGELOG-ny ýörediň we diswiwasiýa syýasatyny berjaý ediň. Şonda täzelenmeler adaty, öňünden aýdyp boljak we howpsuz bolar - we infrastruktura we API-ler işewürlige täsir etmezden öser.