Versioning semantic

Versioning semantic

1) Ce este SemVer și de ce este necesar

• MAJOR - schimbări de rupere.
• MINOR este o nouă caracteristică compatibilă cu API.
• PATCH - remedieri de defecte reversibile.

Scopul: de a conveni asupra stabilității contractelor și de a reduce costul upgrade-urilor.

2) Formatul versiunii

• MAIORULE. MINOR. PLASTURE [-PRERELEASE] [+ BUILD] '

`1. 4. 7 'este o versiune stabilă.
`1. 5. 0-rc. 2 '- pre-eliberare (candidat de lansare nr.2).
`2. 0. 0 + linux. arm64 '- metadate de construcție (nu afectează comparația versiunii).

1. În primul rând, „MAJOR” este comparat, apoi „MINOR”, apoi „PATCH”.

2. Pre-lansările sunt mai mici decât versiunea stabilă corespunzătoare: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Construiți metadate ('+...') nu afectează ordinea: '1. 2. 0+001 == 1. 2. 0`.

3) Ceea ce contează ca schimbare de rupere

• Ștergerea/redenumirea/modificarea semnăturii metodelor/punctelor finale publice.
• Modificați formatul de intrare/ieșire (schema JSON, tipuri).
• Modificarea contractelor de eroare (coduri/structuri).
• Modificarea efectelor secundare/SLA (de exemplu, limite stricte sau câmpuri noi obligatorii).

Nu rupe (dacă este implementat corect): adăugarea de câmpuri opționale, extinderea enum cu noi valori (în cazul în care clientul le ignoră), noi puncte finale, noi steaguri cu defaults care nu afectează apelurile curente.

4) Pre-lansări și strategii de canal

• Etichete: 'alpha', 'beta', 'rc'. Exemplu: '2. 3. 0-beta. 3`.
• Canale: noapte alfa beta rc stabil.
• Politică: pre-lansările nu ar trebui să scadă ca dependențe tranzitive pentru ansamblurile de producție implicite.

5) Variază versiunea și precizia constrângerii

5. 1 Nod/npm (SemVer implicit)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(permite MINOR/PATCH, remediază MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(permite PATCH-uri în termen de MINOR).
`1. 4. x "este orice plasture în 1. 4.
Exact PIN: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- limite explicite.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- inclusiv/exclusiv.
Lovituri stricte este recomandat pentru artefacte critice alimentare.

5. 4 module Go

Întotdeauna completați tag-uri „v MAJOR”. MINOR. PATCH ";" v2 + "necesită sufixul modulului "/v2".

Recomandare: pentru aplicații - ace exacte (builds reproductibile). Pentru biblioteci - intervale de îngrijire (facilitați actualizări fără rupere).

6) CHANGELOG и Commits convenționale

Jurnalul de schimbare structurat îmbunătățește transparența.

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 'и т. д.
Un semn de exclamare sau "BREAKING CHANGE 'block declară un MAJOR.
CHANGELOG este generat din istoria comitetelor (eliberarea notelor de către roboți).

7) Politica de versioning pentru API

API-uri publice: SemVer strict; de rupere → MAJOR.
HTTP/REST: versioning by URL/header: '/v1/... ', '/v2/...' sau 'Accept: cerere/vnd. org. serviciu. v2 + json '.
Scheme JSON: extensii minore - noi câmpuri opționale; major - ștergerea/modificarea obligatorie.
gRPC/Protobuf: adăugați câmpuri noi cu numere noi; Nu reutilizați numerele de câmp ștergând → de depreciere, fără a le rupe pe cele existente.

8) Scheme de date și migrație

Migrările bazelor de date sunt sincronizate cu versiunile app @ 1. 8. 0 'requires' schema @ 1. 8. x ".
Pentru modificarea schemei - faze: extindere (adăugare), migrare, contract (ștergere). Faceți upgrade la MAJOR numai atunci când ștergeți vechiul contract.
Susțineți scrierea/citirea dublă pe durata migrației.

9) Monorepos și microservices

Multi-pachet: fiecare pachet are propriul său "MAJOR. MINOR. PLASTURE "; ciclu comun de eliberare rădăcină numai pentru meta artefacte.

• Versiuni independente (Lerna/Changesets) - crește izolarea.
• Blocare-pas - comunicare mai ușoară, dar mai multe false MAJORS.
• Pentru microservicii, fixați contractele (OpenAPI/Protobuf) cu o versiune separată: 'contract @ 2. 1. 0 ', serviciul îl urmează.

10) Automatizarea versiunilor în 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

Generarea CHANGELOG, publicarea notelor de lansare, actualizarea dependențelor în GitOps repo, verificarea faptului că „principal” indică întotdeauna ultima etichetă stabilă.

11) Politica de privare

Anunț: marcați funcționalitatea ca depreciată în versiunea MINOR, dați termen EOL (de ex. 90 de zile).
Observabilitate: Conectați utilizarea punctelor finale moștenite cu contextul utilizator/chiriaș.
Ștergere: în următorul MAJOR. Documentați calea de migrare.

12) Exemple și șabloane

12. 1 Expresie regulată de validare 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 Exemple de comparații

`1. 2. 3` < `1. 10. 0 '(COMPARAŢIE MINORĂ).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3 + construi. 5` == `1. 2. 3`.

12. 3 Politica de dependență (exemplu 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) Anti-modele

Folosind „cele mai recente ”/tag-uri plutitoare în prod.
Îmbunătățire majoră fără defecțiuni reale („versiuni de marketing”).
Modificări ascunse de rupere sub masca de „PATCH”.
Pre-eliberarea în dependențele tranzitive ale aplicațiilor de producție.
Schimbați artefactul fără o nouă etichetă (versiuni mutabile).
Versiuni de cod inconsecvente și scheme de baze de date.

14) Lista de verificare a implementării (0-45 zile)

0-10 zile

Acceptați SemVer ca standard obligatoriu, aprobați criteriile de rupere.
Includeți Commits convenționale și un șablon de PR cu un câmp 'BREAKING CHANGE'.

11-25 zile

Conectați semantic-release/changesets, autogenerare CHANGELOG.
Configurați semnarea și publicarea artefactelor împotriva etichetei vX. Y.Z '.

26-45 zile

Introduceți politica de depreciere și telemetrie pentru utilizarea API moștenire.
Sincronizați versiunile contractuale (OpenAPI/Proto) și serviciile.
Interziceți „cele mai recente” și etichetele mutabile la nivelul politicii (reglementările OPA/CI).

15) Valorile maturității

% din artefacte publicate numai de eticheta SemVer.
Timpul mediu de migrare între versiunile MINOR.
Numărul de incidente din cauza schimbărilor ascunse de rupere.
Acoperirea comisioanelor convenționale în depozite (> 95%).
Proporția de dependențe fără intervale plutitoare în produs (> 90%).

16) Când SemVer nu este necesar

Prototipuri rapide interne fără consumatori externi (versionarea datată este potrivită).
Date/modele cu caracteristici experimentale (mai bine Model/Schema Versioning cu compatibilitate la nivel de convertor).
Pachete de conținut fără un API public stabil.

17) Concluzie

SemVer este un contract de încredere între producător și consumator. Definiți în mod clar ce rupe compatibilitatea, automatizați recunoașterea tipului de eliberare și publicarea artefactelor, mențineți un CHANGELOG transparent și respectați politicile de privare. Apoi actualizările vor deveni de rutină, previzibile și sigure - iar infrastructura și API-urile se vor dezvolta fără șocuri pentru afacere.