Սեմանտիկ տարբերակումը
Սեմանտիկ տարբերակումը
1) Ի՞ նչ է SemVer-ը և ինչո՞ ւ է այն անհրաժեշտ։
SemVer-ը կանխատեսելի կանոններ է տալիս արտեֆակտներին (գրադարաններ, API, ծառայություններ, սխեմաներ), որպեսզի սպառողները հասկանան, թե ինչ ակնկալել նորարարությունից
MAJOR-ը անհամատեղելի փոփոխություններ են (breaking changes)։
MINOR-ը նոր ֆունկցիոնալություն է, որը կապված է API-ի հետ։
PATCH - թերությունների փոխկապակցված ուղղումներ։
Նպատակը 'պայմանավորվել կայունության մասին և նվազեցնել մրցույթի արժեքը։
2) Տարբերակի ձևաչափը
Հիմնական ձևաչափը
`MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`
`1. 4. 7 'կայուն թողարկումը։
`1. 5. 0-rc. 2 'pre-թողարկումը (releast candidate 242)։
`2. 0. 0+linux. arm64 '- build-medians (չեն ազդում տարբերակների համեմատության վրա)։
Համեմատության կանոնները
1. Սկզբում համեմատվում են «MAJOR», ապա 'MINOR «, ապա' PATCH»։
2. Pre-ալգորիթմները ավելի քիչ են, քան կայուն տարբերակը '<1։ 2. 0-rc. 1 < 1. 2. 0`.
3. Build-մետատվյալներ («+...») չեն ազդում կարգի վրա '1։ 2. 0+001 == 1. 2. 0`.
3) Ի՞ նչ է համարվում breaking change
Breaking change-ը ցանկացած փոփոխություն է, որը պահանջում է սպառողի գործողությունները
Հեռացում/վերանվանել/փոխել հանրային մեթոդների/էնդպոինտների ազդանշանը։
Մուտքի/ելքի ձևաչափի փոփոխությունը (JSON-սխեմա, տեսակներ)։
Վերջնական սխալների փոփոխությունը (108/կառուցվածք)։
Side-effects/SLAS-ի փոփոխությունը (օրինակ, խիստ լիմիտներ կամ նոր պարտադիր դաշտեր)։
Ոչ թե breaking (ճիշտ իրականացման դեպքում) 'ավելացնելով միգրացիոն դաշտերը, ընդլայնումը նոր արժեքներ (եթե հաճախորդը անտեսում է դրանք), նոր էնդպոինտներ, նոր դրոշներ դեֆոլտներով, որոնք չեն ազդում ռուսական մարտահրավերների վրա։
4) Pre-Aleksands և կանոնական ռազմավարություններ
Պրե-ֆորումները թույլ են տալիս թեստավորել առանց SemVer խոստումների խախտման
Իսպանիա ՝ «alpha», «beta», «rc»։ Օրինակ ՝ '2։ 3. 0-beta. 3`.
Ալիքները ՝ nightly www.alpha www.beta www.rc www.stable։
Քաղաքականությունը 'pre-line չպետք է լինի տրանզիտիվ կախվածություն լռելյայն համար։
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 '- ցանկացած վճար 1-ում։ 4.
Ճշգրիտ pin: <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 »։
Առաջարկություն 'դիմումների համար' ճշգրիտ պիններ (reproducible builds)։ Գրադարանների համար 'caret-միջակայքը (հեշտացնել նորարարությունները առանց կոտրվածքների)։
6) CHANGELOG и Conventional Commits
Կառուցվածքային փոփոխության ամսագիրը բարձրացնում է թափանցիկությունը։
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-ը ստեղծվում է կոմունիտների պատմությունից (releant-notes bots)։
7) Տարբերակման քաղաքականությունը API-ի համար
Հանրային API 'խիստ SemVer; breaking → MAJOR.
HTTP/REST: URL/վերնագիր ՝ "/v1/... ", "/v2/..." կամ "Accept: Accept: Acport/vnd։ org. service. v2+json`.
JSON-սխեմաները 'մինորալ ընդարձակումները' նոր միգրացիոն դաշտեր։ major - հեռացում/փոփոխություն պարտադիր։
GRPC/Winobuf: ավելացրեք նոր դաշտեր նոր համարներով։ մի օգտագործեք դաշտերի համարները. deprecate-ի հեռացումը ոչ թե «կոտրել» գոյություն ունեցող։
8) Տվյալների և կոդերի սխեմաները
BD-ի իրականացումը համաժամեցված է ծրագրի տարբերակների հետ '<app @ 1։ 8. 0 'պահանջում է <schema @ 1։ 8. x`.
Սխեմայի փոփոխության համար 'expand (ավելացնել), migrate, www.ract (հեռացնել)։ Տարբերակը բարձրացրեք MAJOR-ին միայն այն ժամանակ, երբ հեռացնում եք հին պայմանագիրը։
Աջակցեք կրկնակի ձայնագրությանը/ընթերցանությանը ժամանակի համար։
9) Մոնորեպոն և միկրովայրկյանները
Multi-package: յուրաքանչյուր պայուսակ իր «MAJOR» -ը։ MINOR. PATCH`; ածխաջրածինների ընդհանուր ցիկլը միայն մետա-արտեֆակտների համար է։
Տարբեր ռազմավարություններ
Independent versions (Lerna/Changesets) - ուժեղացնում է մեկուսացումը։
Nok-step-ը ավելի հեշտ հաղորդակցությունն է, բայց ավելի կեղծ MAJOR-ը։
Միկրովայրցիների համար արձանագրեք պայմանագրեր (OpenAPI/Eurobuf) առանձին տարբերակով '"www.ract @ 2։ 1. 0 ', ծառայությունը պետք է նրան։
10) Ածխաջրածինների ավտոմատացումը CI/CD-ում
Conventional Commits-ի վրա հիմնված տարբերակի ինքնությունը
`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_VERSIONCHANGELOG-ի գեներացիան, ռելիզի հրապարակումը, GitOps-ում կախվածության նորարարությունը, ստուգումը, որ «main» -ը միշտ ցույց է տալիս վերջին կայուն թեգը։
11) Ապակայունացման քաղաքականությունը (deprecation policy)
Գովազդ 'տեղադրեք ֆունկցիոնալությունը որպես deprecated MINOR-2019-ում, եկեք EOL (օրինակ ՝ 90 օր)։
Դիտարկումը 'տրամաբանեք հնացած էնդպոինտների օգտագործումը user/tenault համատեքստով։
Հեռացում 'հաջորդ MAJOR-ում։ Տեղեկացրու, թե ինչպես կարելի է հասնել։
12) Օրինակներ և ձևանմուշներ
12. 1 SemVer validation արտահայտությունը
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: true13) Anti-patterna
"Latest '/լողացող թեգերի օգտագործումը երկարության մեջ։
MAJOR-ի բարձրացումը առանց իրական կոտրվածքների («մարքեթինգային տարբերակներ»)։
Թաքնված breaking-փոփոխությունները «PATCH» -ի տակ։
Պրե-ֆորումները պրո-ծրագրերի տրանզիտիվ կախվածություններում։
Փոխեք արտեֆակտը առանց նոր թեգի (մուտաբային տարբերակներ)։
Կոդի և BD սխեմայի չհամաձայնեցված տարբերակները։
14) Ներդրման թուղթ (0-45 օր)
0-10 օր
Վերցրեք SemVer-ը որպես պարտադիր դեղամիջոց, հաստատեք կոտրման չափանիշները։
Միացրեք Conventional Commits-ը և PR-ը «BREAKING CHANGE» դաշտով։
11-25 օր
Միացրեք semantic-rele.ru/changesets, CHANGELOG-ի ավտոմատ արտադրությունը։
Պարեք ստորագրությունը և արտեֆակտների հրատարակումը «vX» պիտակի վրա։ Y.Z`.
26-45 օր
Մուտքագրեք deprecation policy և հեռաչափություն հնացած API-ի օգտագործման համար։
Համաժամեցրեք կոդավորման տարբերակները (OpenAPI/Pro) և ծառայությունները։
Արգելեք «latest» և մուտաբելային թեստերը քաղաքականության մակարդակում (ORA/CI)։
15) Հասունության մետրերը
արտեֆակտների տոկոսը, որոնք հրատարակվել են միայն SemVer-ի թեգով։
Միջին ժամանակը կատարվում է MINOR տարբերակների միջև։
Գնումների քանակը թաքնված breaking-փոփոխությունների պատճառով։
Conventional Commits-ի ծածկույթը ռեպոզատորներում (> 95%)։
Կախվածության մասնաբաժինը առանց լողացող միջակայքերի վաճառքում (> 90 տոկոսը)։
16) Երբ SemVer-ը կարիք չունի
Ներքին արագ նախատիպերը առանց արտաքին սպառողների (հարմար է թվայնացված տարբերակումը)։
Այս/մոդելները փորձարկման ավարտներով (ավելի լավ է Model/Schema Versioning-ը փոխարկիչների մակարդակում)։
Բովանդակության փաթեթներ առանց կայուն հանրային API-ի։
17) Եզրակացություն
SemVer-ը արտադրողի և սպառողի միջև վստահության պայմանագիր է։ Հստակ որոշեք, թե ինչ է կոտրում համատեղելիությունը, ավտոմատիզացնում է ածխաջրածինների տեսակների ճանաչումը և արտեֆակտների հրապարակումը, վարեք թափանցիկ CHANGELOG-ը և պահպանեք ապակայունացման քաղաքականությունը։ Այդ ժամանակ նորարարությունները կդառնան իրական, կանխատեսելի և անվտանգ, իսկ ենթակառուցվածքը և API-ը կզարգանան առանց բիզնեսի ցնցումների։