სემანტიკური ვერსია

სემანტიკური ვერსია

1) რა არის SemVer და რატომ არის ეს საჭირო

• MAJOR - შეუთავსებელი ცვლილებები.
• MINOR არის ახალი ფუნქციონირება, რომელიც თავსებადია API- სთან.
• PATCH - დეფექტების შექცევადი თავსებადი კორექტირება.

მიზანი: შეთანხმდნენ ხელშეკრულებების სტაბილურობასა და განახლების ღირებულების შემცირებაზე.

2) ვერსიის ფორმატი

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

`1. 4. 7 '- სტაბილური გამოშვება.
`1. 5. 0-rc. 2 '- წინასწარი გამოშვება (release candidate 22).
`2. 0. 0+linux. arm64 '- build მეტამონაცემები (გავლენას არ ახდენს ვერსიების შედარებაზე).

1. ჯერ შედარებულია 'MAJOR', შემდეგ 'MINOR', შემდეგ 'PATCH'.

2. წინასწარი გამოშვებები ნაკლებია, ვიდრე შესაბამისი სტაბილური ვერსია: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Build მეტამონაცემები ('+...') არ ახდენენ გავლენას წესრიგზე: '1. 2. 0+001 == 1. 2. 0`.

3) რა არის breaking შეცვლა

• საჯარო მეთოდების/ენდოინტების ხელმოწერის/სახელის შეცვლა/შეცვლა.
• შესვლის/გასვლის ფორმატის შეცვლა (JSON სქემა, ტიპები).
• შეცდომების ხელშეკრულებების შეცვლა (კოდები/სტრუქტურები).
• side-effects/SLAs- ის შეცვლა (მაგალითად, მკაცრი ლიმიტები ან ახალი სავალდებულო ველები).

არა breaking (სწორი განხორციელებით): არჩევითი ველების დამატება, enum- ის გაფართოება ახალი მნიშვნელობებით (თუ კლიენტი უგულებელყოფს მათ), ახალი endpoints, ახალი დროშები ნაგულისხმევებით, რომლებიც გავლენას არ ახდენენ მიმდინარე გამოწვევებზე.

4) წინასწარი გამოშვებები და არხის სტრატეგიები

• ეტიკეტები: 'alpha', 'beta', 'rc'. მაგალითი: '2. 3. 0-beta. 3`.
• არხები: nightly - alpha - beta - rc - stable.
• პოლიტიკა: წინასწარი გამოშვებები არ უნდა აღმოჩნდეს, როგორც გარდამავალი დამოკიდებულება ნაგულისხმევი შეკრებისთვის.

5) ვერსიების დიაპაზონი და დამოკიდებულების სიზუსტე

5. 1 Node/npm (SemVer ნაგულისხმევი)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(საშუალებას აძლევს MINOR/PATCH, აფიქსირებს MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(საშუალებას აძლევს PATCH MINOR- ში).
`1. 4. x '- ნებისმიერი plat 1. 4.
ზუსტი პინი: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- აშკარა საზღვრები.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) "- ინკლუზიურად/ექსკლუზიურად.
რეკომენდებულია მკაცრი დარტყმა პროდ-კრიტიკული არტეფაქტებისთვის.

5. 4 Go modules

ყოველთვის სრული ჭდეები 'vMAJOR. MINOR. PATCH ';' v2 + 'მოითხოვს სუფიქსის მოდულს '/v2'.

რეკომენდაცია: აპლიკაციებისთვის - ზუსტი ხარვეზები. ბიბლიოთეკებისთვის - კარეტის დიაპაზონი (განახლებების შემსუბუქება შეფერხებების გარეშე).

6) CHANGELOG и 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` и т. д.
ძახილის ნიშანი ან ბლოკი „BREAKING CHANGE“ აცხადებს MAJOR- ის ზრდას.
CHANGELOG წარმოიქმნება კომუნიკაციების ისტორიიდან.

7) ვერსიის პოლიტიკა API- სთვის

საზოგადოებრივი API: მკაცრი SemVer; breaking → MAJOR.
HTTP/REST: URL/სათაური ვერსია: '/v1/... ', '/v2/...' ან 'Accept: განაცხადი/vnd. org. service. v2+json`.
JSON სქემები: უმცირესობის გაფართოება - ახალი არჩევითი ველები; მაიორი - სავალდებულო მოცილება/ცვლილება.
GRPC/Protobuf: დაამატეთ ახალი ველები ახალი ნომრებით; ნუ გამოიყენებთ მინდვრის ნომრებს; მოცილება არის deprecate და არა არსებული „დაშლა“.

8) მონაცემთა სქემები და მიგრაცია

BD მიგრაციები სინქრონიზებულია განაცხადის ვერსიებთან: 'app @ 1. 8. 0 'schema @ 1. 8. x`.
მიკროსქემის ცვლილებების შესაცვლელად - ფაზა: გამოცდა (დამატება), migrate, contract (წაშლა). ვერსია MAJOR- ზე გაზარდეთ მხოლოდ მაშინ, როდესაც ძველი კონტრაქტი ამოიღეთ.
შეინარჩუნეთ ორმაგი ჩაწერა/კითხვა მიგრაციის დროს.

9) მონორეპო და მიკრო სერვისები

მრავალჯერადი პაკეტი: თითოეულ პაკეტს აქვს საკუთარი 'MAJOR. MINOR. PATCH`; გამოშვებების ზოგადი ფესვის ციკლი მხოლოდ მეტა არტეფაქტებისთვის.

• დამოუკიდებელი ვერსიები (Lerna/Changesets) - აძლიერებს იზოლაციას.
• Lock-step უფრო ადვილია კომუნიკაცია, მაგრამ უფრო ცრუ MAJOR.
• მიკრო სერვისებისთვის ჩაწერეთ კონტრაქტები (OpenAPI/Protobuf) ცალკეული ვერსიით: 'contract @ 2. 1. 0 ', მომსახურება მიჰყვება მას.

10) გამოშვების ავტომატიზაცია CI/CD- ში

• `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 თაობა, ნოუთბუქების გამოქვეყნება, GitOps-repo დამოკიდებულებების განახლება, შემოწმება, რომ 'main' ყოველთვის მიუთითებს ბოლო სტაბილურ ჭდეზე.

11) დეპრესიის პოლიტიკა

განცხადება: შეაფასეთ ფუნქციონირება, როგორც MINOR- ის გამოშვებაში, მოდით, EOL ვადა (მაგალითად, 90 დღე).
დაკვირვება: გაანალიზეთ მოძველებული ენდოინების გამოყენება user/tenant კონტექსტით.
მოცილება: შემდეგი MAJOR. აღწერეთ მიგრაციის გზა.

12) მაგალითები და შაბლონები

12. 1 SemVer ვალიდაციის რეგულარული გამოხატვა

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 შედარებების მაგალითები

`1. 2. 3` < `1. 10. 0 '(შედარება MINOR- ზე).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 დამოკიდებულების პოლიტიკა (მაგალითი YAML)

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) ანტი შაბლონები

'latest '/მცურავი ჭდეების გამოყენება გაყიდვაში.
MAJOR- ის ზრდა რეალური ხარვეზების გარეშე („მარკეტინგული ვერსიები“).
ფარული breaking ცვლილებები „PATCH“ ქვეშ.
წინასწარი გამოშვებები პროდ პროგრამების გარდამავალ დამოკიდებულებებში.
შეცვალეთ არტეფაქტი ახალი ჭდის გარეშე (ტალახის ვერსიები).
კოდისა და DD სქემების არაკოორდინირებული ვერსიები.

14) განხორციელების სიის სია (0-45 დღე)

0-10 დღე

მიიღეთ SemVer, როგორც სავალდებულო სტანდარტი, დაამტკიცეთ ხარვეზების კრიტერიუმები.
ჩართეთ Conventional Commits და PR შაბლონი 'BREAKING CHANGE'.

11-25 დღე

დააკავშირეთ semantic-release/changesets, CHANGELOG ავტომატური წარმოება.
ხელმოწერის პარამეტრები და არტეფაქტების გამოქვეყნება 'vX'. Y.Z`.

26-45 დღე

შეიყვანეთ დეპრესიის პოლიტიკა და მოძველებული API გამოყენების ტელემეტრია.
შეამოწმეთ ხელშეკრულებების ვერსიები (OpenAPI/Proto) და სერვისები.
აიკრძალეთ 'latest' და მუტაბელური ჭდეები პოლიტიკის დონეზე (ORA/CI რეგულაციები).

15) სიმწიფის მეტრიკა

მხოლოდ SemVer- ის მიხედვით გამოქვეყნებული არტეფაქტების%.
საშუალო მიგრაციის დრო MINOR ვერსიებს შორის.
ინციდენტების რაოდენობა ფარული შესვენების გამო.
Conventional Commits- ის საფარი საცავებში (> 95%).
დამოკიდებულების წილი მცურავი დიაპაზონის გარეშე გაყიდვაში (> 90%).

16) როდესაც SemVer არ არის საჭირო

შიდა სწრაფი პროტოტიპები გარე მომხმარებლების გარეშე (დათარიღებული ვერსია შესაფერისია).
მონაცემები/მოდელები ექსპერიმენტული ფილიალებით (უკეთესია Model/Schema Versioning, გადამყვანი დონის თავსებადობით).
შინაარსის პაკეტები სტაბილური საზოგადოებრივი API- ს გარეშე.

17) დასკვნა

SemVer არის ნდობის ხელშეკრულება მწარმოებელსა და მომხმარებელს შორის. მკაფიოდ განსაზღვრეთ, თუ რა არღვევს თავსებადობას, ავტომატურად ამოიცნობთ გამოშვებების ტიპებს და გამოაქვეყნეთ არტეფაქტები, ჩაატარეთ გამჭვირვალე CHANGELOG და დაიცავით დემარკაციის პოლიტიკა. შემდეგ განახლებები გახდება რუტინული, პროგნოზირებული და უსაფრთხო - და ინფრასტრუქტურა და API განვითარდება ბიზნესის შოკის გარეშე.