Wersioning semantyczny

1) Co to jest SemVer i dlaczego jest potrzebne

SemVer ustawia przewidywalne zasady przypisywania wersji do artefaktów (bibliotek, interfejsów API, usług, schematów), dzięki czemu konsumenci rozumieją, czego mają oczekiwać po aktualizacji:

MAJOR - zmiany łamiące.
MINOR to nowa funkcja zgodna z API.
PATCH - odwracalne poprawki usterek.

Cel: uzgodnienie stabilności umów i zmniejszenie kosztów modernizacji.

2) Format wersji

Format podstawowy:

"MAJOR. DROBNE. PLASTER [-PRERELEASE] [+ BUILD] "

`1. 4. 7 'to stabilne uwolnienie.
`1. 5. 0-rc. 2 "- przed zwolnieniem (kandydat na zwolnienie nr 2).
`2. 0. 0 + linux. arm64 '- metadane konstrukcyjne (nie wpływają na porównanie wersji).

Zasady porównywania:

1. Najpierw porównuje się „MAJOR”, następnie „MINOR”, a następnie „PATCH”.

2. Wstępne wydania są mniejsze niż odpowiednia stabilna wersja: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Metadane budowy ('+...') nie mają wpływu na kolejność: '1. 2. 0+001 == 1. 2. 0`.

3) Co liczy się jako złamanie zmiany

Przełamanie zmian - każda zmiana wymagająca działania konsumentów:

Usuń/zmień nazwę/sygnaturę publicznych metod/punktów końcowych.
Zmień format wejścia/wyjścia (schemat JSON, typy).
Modyfikacja umów o błąd (kody/struktury).
Zmiana skutków ubocznych/SLA (na przykład rygorystyczne granice lub nowe wymagane pola).

Nie łamanie (jeśli poprawnie zaimplementowane): dodanie opcjonalnych pól, rozszerzenie enum o nowe wartości (jeśli klient je ignoruje), nowe punkty końcowe, nowe flagi z domyślnymi parametrami, które nie wpływają na bieżące połączenia.

4) Premiery i strategie kanałów

Wstępne wydania pozwalają przetestować bez łamania obietnic SemVer:

Tagi: 'alfa', 'beta', 'rc'. Przykład: '2. 3. 0-beta. 3`.
Kanały: noc → alfa → beta → rc → stabilna.
Polityka: zwolnienia wstępne nie powinny ulegać zmniejszeniu jako zależności transywalne dla domyślnych zespołów produkcyjnych.

5) Zakresy wersji i dokładność ograniczeń

Prawdziwe ekosystemy używają wyrażeń zakresu:

5. 1 węzeł/npm (domyślnie SemVer)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(umożliwia MINOR/PATCH, naprawia MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(pozwala PATCH w ramach MINOR).
`1. 4. x 'to dowolny plaster w 1. 4.
Dokładny pin: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- wyraźne granice.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) "- inclusive/exclusive.
Surowe kopanie jest zalecane do artefaktów krytycznych dla żywności.

5. 4 Moduły Go

Zawsze kompletne znaczniki 'vMAJOR'. DROBNE. PATCH ';' v2 + 'wymaga przyrostka modułu '/v2'.

Zalecenie: dla zastosowań - dokładne szpilki (odtwarzalne budowle). Dla bibliotek - zakresy caret (ułatwić aktualizacje bez uszkodzenia).

6) CHANGELOG - Commits konwencjonalne

Strukturalny dziennik zmian poprawia przejrzystość.

Zobowiązania konwencjonalne:


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' ма. д.
Wykrzyknik lub „przełamanie zmiany” blok deklaruje MAJOR.
CHANGELOG jest generowany z historii commits (release-notes by bots).

7) Polityka weryfikacyjna dla API

Publiczne interfejsy API: ścisły SemVer; łamanie → MAJOR.
HTTP/REST: wersioning przez URL/nagłówek: '/v1/... „, ”/v2/...„ lub ”Accept: application/vnd. org. usługi. v2 + json '.
Schematy JSON: drobne rozszerzenia - nowe pola opcjonalne; major - skreślić/zmienić obowiązkowe.
gRPC/Protobuf: dodać nowe pola z nowymi numerami; Nie należy ponownie używać numerów pól usuwających deprecate →, nie łamiąc istniejących.

8) Systemy danych i migracji

Migracje baz danych są synchronizowane z wersjami app @ 1. 8. 0 'wymaga' schema @ 1. 8. x ".
Do łamania zmian schematu - fazy: expand (add), migrate, contract (delete). Uaktualnij do programu MAJOR tylko wtedy, gdy usuniesz stary kontrakt.
Obsługa podwójnego zapisu/odczytu na czas trwania migracji.

9) Monorepozycje i mikroservice

Pakiet wielopakowy: każdy pakiet ma swój własny "MAJOR. DROBNE. PATCH "; wspólny cykl uwalniania pierwiastków tylko dla meta artefaktów.

Różne strategie:

Niezależne wersje (Lerna/Changesets) - zwiększa izolację.
Lock-step - łatwiejsza komunikacja, ale bardziej fałszywe MAJORS.
W przypadku mikroservices, naprawić kontrakty (OpenAPI/Protobuf) z osobną wersją: 'contract @ 2. 1. 0 ", usługa podąża za nim.

10) Automatyzacja wydań w CI/CD

Automatyczne obliczanie wersji na podstawie konwencjonalnych zatwierdzeń:

'fix' → 'PATCH', 'feat' → 'MINOR', '! '/' BREAKING' → 'MAJOR'.

Autotegi i podpis artefaktowy:

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

Generacja CHANGELOG, publikacja notatek, aktualizacja zależności w GitOps repo, sprawdzanie, że „główny” zawsze wskazuje na ostatni stabilny tag.

11) Polityka deprywacji

Ogłoszenie: funkcja znaku jako przestarzała w wydaniu MINOR, podać termin EOL (np. 90 dni).
Obserwowalność: Zaloguj wykorzystanie dotychczasowych punktów końcowych z kontekstem użytkownika/najemcy.
Usunięcie: w następującym MAJOR. Dokumentuj ścieżkę migracji.

12) Przykłady i szablony

12. 1 Regularne wyrażenie walidacji 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 Przykłady porównań

`1. 2. 3` < `1. 10. 0 '(NIEWIELKIE porównanie).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3 + budowa. 5` == `1. 2. 3`.

12. 3 Polityka zależności (przykład 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) Anty-wzory

Używając 'najnowszych '/pływających znaczników w prod.
GŁÓWNE ulepszenie bez rzeczywistych podziałów („wersje marketingowe”).
Ukryte zmiany łamania pod pozorem 'PATCH'.
Wstępne uwolnienia w zależności transitive aplikacji produkcyjnych.
Zmień artefakt bez nowego znacznika (mutowalne wersje).
Niespójne wersje kodów i schematy baz danych.

14) Lista kontrolna wdrażania (0-45 dni)

0-10 dni

Akceptuj SemVer jako obowiązkowy standard, zatwierdzaj kryteria łamania.
Zawierać konwencjonalne Commits i szablon PR z 'BREAKING CHANGE' pole.

11-25 dni

Podłącz semantyczne/changesets, autogenerację CHANGELOG.
Konfiguracja podpisywania i publikowania artefaktów na tagu vX. Y.Z '.

26-45 dni

Wprowadź politykę deprecacji i telemetrię dla legalnego użycia API.
Synchronizuj wersje kontraktowe (OpenAPI/Proto) i usługi.
Zakazać „najnowszych” i mutowalnych znaczników na poziomie polityki (przepisy OPA/CI).

15) Wskaźniki zapadalności

% artefaktów opublikowanych tylko przez SemVer tag.
Średni czas migracji między wersjami MINOR.
Liczba incydentów spowodowanych ukrytymi zmianami.
Zasięg konwencjonalnych zatwierdzeń w repozytoriach (> 95%).
Odsetek zależności bez zakresów pływających w produkcie (> 90%).

16) Kiedy SemVer nie jest potrzebny

Wewnętrzne szybkie prototypy bez zewnętrznych konsumentów (odpowiedni jest datowany wersioning).
Dane/modele z funkcjami eksperymentalnymi (lepszy Model/Schema Versioning z kompatybilnością na poziomie konwertera).
Pakiety treści bez stabilnego publicznego interfejsu API.

17) Wniosek

SemVer jest umową powierniczą między producentem a konsumentem. Jasno określić, co łamie kompatybilność, automatyczne rozpoznawanie typu wydania i publikowanie artefaktów, utrzymać przejrzysty CHANGELOG i przestrzegać zasad deprywacji. Następnie aktualizacje staną się rutynowe, przewidywalne i bezpieczne - a infrastruktura i interfejsy API będą rozwijać się bez wstrząsów dla biznesu.

Wersioning semantyczny