Wersjonowanie artefaktów: semver, tagi i release notes automatycznie

Gdzie zaczyna się bałagan: realne skutki złego wersjonowania

Telefon na on-callu. Produkcja leży, rollback musi pójść w ciągu kilku minut. Wchodzisz do rejestru kontenerów i widzisz: pięć różnych obrazów oznaczonych jako latest, kilka z tagiem test, parę bez żadnego sensownego oznaczenia. W deploymentach Kubernetesa też „latest”. Nikt nie wie, który obraz jest „tym poprzednim, działającym”. Zaczyna się zgadywanie po dacie zbudowania, przegląd commitów, desperackie próby odtworzenia poprzedniego builda. To jest moment, w którym brak przemyślanego wersjonowania artefaktów boleśnie wychodzi na wierzch.

W mniejszym zespole taka sytuacja często przez lata nie występuje, więc rośnie przekonanie, że „jakoś to działa”. Do pierwszego incydentu produkcyjnego lub audytu bezpieczeństwa. Wtedy nagle okazuje się, że nikt nie jest w stanie odpowiedzieć jasno na pytania: jaka dokładnie wersja aplikacji jest na produkcji, który commit ją zbudował, jakie zmiany zawierała względem poprzedniej.

Cichy koszt „wersjonowania na słowo honoru”

Brak spójnego wersjonowania artefaktów rzadko wybucha od razu. Zwykle generuje małe, powtarzalne opóźnienia i ryzyka:

• debugowanie trwa dłużej, bo trzeba zgadywać, z którego builda pochodzi błąd,
• release notes powstają ręcznie, z maili i Jiry, bo nikt nie łączy wydań z tagami w Git,
• zespoły integrujące się z API nie wiedzą, do której wersji się odwołują,
• hotfixy muszą być „dogadane na callu”, bo nie ma jasnej procedury wersjonowania i tagowania.

Każda z tych rzeczy osobno wygląda niewinnie. Raz ktoś zapomni podbić numer wersji, raz ktoś nadpisze tag, raz ktoś wypchnie obraz z innym tagiem niż w manifestach. Po roku okazuje się, że nikt nie ufa oznaczeniom wersji, więc wersjonowanie istnieje tylko formalnie, a i tak wszystko trzeba potwierdzać z osobami, które „pamiętają, jak było robione wydanie”.

Mit: „w małym zespole się dogadamy”

Częsta narracja: „Jest nas pięciu, wszyscy się znamy, nie potrzebujemy formalnego semver i automatycznego release notes, wystarczy, że napiszemy na Slacku, że wjechała wersja nowa”. Rzeczywistość wygląda inaczej:

• ktoś odchodzi z zespołu i nagle znika jedyna osoba, która „trzymała w głowie” numerację,
• wchodzi nowy projekt lub integracja zewnętrzna, która potrzebuje stabilnych wersji API,
• pojawia się wymóg audytu (np. zgodności z normami), który wymaga śledzenia konkretnych wydań.

Wersjonowanie artefaktów to nie tylko „ładne numerki”. To mechanizm jednoznacznej identyfikacji tego, co naprawdę zostało zbudowane, przetestowane i wdrożone. Nawet mały zespół może sobie poważnie utrudnić życie, jeśli polega wyłącznie na „dogadaniu się”.

Co chcemy osiągnąć, automatyzując wersjonowanie

Dobrze ustawione wersjonowanie artefaktów, oparte o semver, tagi Git i automatyczne release notes, ma bardzo konkretny cel:

• jednoznaczna identyfikacja artefaktu – po numerze wersji od razu wiadomo, co to jest, jaki kod zawiera i gdzie został zbudowany,
• powtarzalne wydania – ten sam commit zawsze daje ten sam artefakt; wersja nie zmienia się „po drodze”,
• możliwość audytu zmian – do każdego wydania można w prosty sposób wygenerować listę zmian (release notes),
• bezpieczne rollbacki – wiadomo, jaki dokładnie artefakt był poprzednio na produkcji i da się go łatwo ponownie wdrożyć.

Celem nie jest „idealnie podręcznikowy semver”, tylko system, który zdejmuje z ludzi konieczność pamiętania, co gdzie jest, i minimalizuje przestrzeń na zgadywanie.

Co właściwie wersjonujemy w CI/CD: artefakty i ich powiązania

Artefakt w praktyce DevOps

„Artefakt” brzmi sucho, ale pod spodem kryje się wszystko, co pipeline produkuje i co realnie wdrażasz lub udostępniasz:

• obrazy Docker (kontenery),
• paczki bibliotek (npm, Maven, PyPI, NuGet, Cargo itd.),
• binaria CLI lub aplikacje desktopowe,
• Helm charty, manifesty Kubernetes, pliki YAML/JSON z konfiguracją deploymentu,
• archiwa ZIP/TAR dystrybuowane dalej (np. do on-prem klientów).

Mit bywa taki: „wersjonujemy tylko kod, artefakty to pochodna”. W praktyce konsumenci twojego systemu widzą artefakty, nie commit. Kontener na produkcji nie wie, z którego brancha został zbudowany, jeśli nie prześlesz tam tej informacji wersyjnej. To wersja artefaktu jest punktem odniesienia dla integracji, rollbacku i audytu.

Jeden commit, wiele artefaktów

Typowy pipeline DevOps wygląda tak, że z jednego commita powstaje kilka różnych artefaktów. Na przykład:

• frontend: paczka npm oraz obraz Docker,
• backend: obraz Docker,
• Helm chart bundlujący frontend i backend,
• plik manifestu z konfiguracją (np. values.yaml dla każdego środowiska).

Zdarza się wtedy, że różne części pipeline’u używają różnych schematów wersjonowania: paczka npm ma semver, obraz Docker ma tylko latest, Helm chart ma jakąś własną numerację. W efekcie debugowanie „która wersja frontu trafiła do produkcji razem z którym backendem” zamienia się w śledztwo na pół dnia.

Bardziej sensowny model to jedna wersja logiczna systemu, która jest używana we wszystkich artefaktach powstałych z danego commita (lub zestawu commitów). Przykład: commit o tagu v1.4.2 generuje:

• obraz Docker backendu: backend:1.4.2 (+ ew. dodatkowe tagi),
• obraz Docker frontendu: frontend:1.4.2,
• Helm chart: my-app-1.4.2.tgz,
• paczki bibliotek SDK: sdk-js@1.4.2, sdk-java:1.4.2.

Dzięki temu, gdy ktoś mówi „mamy problem w wersji 1.4.2”, od razu wiadomo, o jakim zestawie artefaktów jest mowa. Nie ma już zabawy w dopasowywanie dat buildów.

Przepływ commit → tag → artefakt → deployment

Przejrzysty przepływ pomaga ustalić, gdzie jest źródło prawdy wersji oraz jak powiązane są ze sobą poszczególne elementy:

1. Developer merguje feature do main / master.
2. Pipeline CI buduje kod, uruchamia testy.
3. Na podstawie commitów i/lub pliku wersji pipeline wyznacza numer semver i tworzy tag Git (np. v1.4.2).
4. Ten sam pipeline buduje obrazy Docker i inne artefakty, oznaczając je wersją z taga.
5. Pipeline CD używa wersji artefaktu do deploymentu na środowiska (test → stage → prod), zapisując ją np. jako label na zasobach Kubernetesa.

Kluczowa zasada: commit bez releasowalnego taga semver nie idzie na produkcję. Dzięki temu produkcja jest zawsze zbudowana z jednoznacznie oznaczonego commita, a nie z „jakiegoś tam” stanu brancha. Tagi i wersje artefaktów stają się więc językiem, którym rozmawiają CI/CD, zespół i integracje.

Gdzie trzymać informacje o wersji

Najczęstsze opcje:

• w pliku w repo (np. VERSION, package.json, pom.xml),
• w tagu Git (np. v1.4.2 jako anotowany tag),
• w metadanych artefaktu (np. label Dockera org.opencontainers.image.version),
• w systemie release’ów (np. GitHub Releases, GitLab Releases, własna baza).

Naiwne podejście: „im więcej miejsc z wersją, tym lepiej”. Rzeczywistość: każde dodatkowe miejsce to potencjalna niespójność. Rozsądniej jest wybrać jedno główne źródło prawdy (np. tag Git semver) i z niego generować wszystkie pozostałe informacje wersyjne, a nie odwrotnie.

Semver bez mitologii: jak mapować realne zmiany na major/minor/patch

Rdzeń semver w jednym akapicie

Semantic Versioning (semver) sprowadza się do prostego kontraktu z konsumentem:

• MAJOR – zmiana łamiąca wsteczną kompatybilność (breaking change),
• MINOR – nowe funkcje zgodne wstecznie,
• PATCH – poprawki bez zmiany publicznego kontraktu.

Mit bywa taki: „semver = gwarancja braku bugów w patchu, a major to zawsze rewolucja”. Rzeczywistość: semver nie mówi nic o jakości kodu. Mówi tylko, jakiego typu ryzyka zmiany może oczekiwać konsument.

Jeśli API REST przestaje przyjmować dotychczas akceptowane żądanie, to jest breaking change i wymaga podbicia MAJOR, niezależnie od tego, czy dotyka to 1% czy 90% klientów. Jeśli dodajesz nowy endpoint bez zmiany istniejących – to MINOR. Jeśli poprawiasz walidację lub bug w logice, ale interfejs pozostaje ten sam – to PATCH.

Praktyczne mapowanie zmian na semver

Drobne przykłady pomagają zdjąć niepewność z decyzji „major czy minor?”.

Zmiany w API REST

• Usunięcie pola z odpowiedzi JSON – breaking change → nowy MAJOR. Klient, który oczekuje tego pola, zacznie się sypać.
• Zmiana typu pola (np. z string na int) – breaking change → MAJOR. Nawet jeśli twój frontend to obsłużył, zewnętrzny klient może nie.
• Dodanie nowego pola w odpowiedzi przy zachowaniu dotychczasowych – MINOR. Klient, który ignoruje nieznane pola, działa dalej.
• Zmiana opisu pola w Swaggerze bez zmiany zachowania – PATCH. Kontrakt pozostaje taki sam.

Sporny przypadek to zmiana domyślnej wartości parametru. Jeśli dotychczasowe wywołania bez tego parametru zachowywały się inaczej, to z perspektywy klienta to jest breaking change → MAJOR. Jeżeli zmiana jest neutralna (np. poprawka błędu, który i tak był niezgodny z dokumentacją), można argumentować PATCH, ale wtedy warto jasno opisać to w release notes.

Zmiany w UI, logice i logowaniu

Co z większością „wewnętrznych” zmian, które nie dotykają oficjalnego API?

• Przeróbka layoutu frontendu bez zmiany API backendu – z punktu widzenia API to nadal PATCH/MINOR. Jeśli UI jest także twoim „API” dla użytkownika biznesowego, możesz mimo wszystko chcieć komunikować większe zmiany jako MINOR.
• Optymalizacja zapytań do bazy bez zmiany zachowania – PATCH.
• Dodanie nowego logowania, nowych metryk, feature flag – PATCH, o ile nie zmieniasz publicznego API.
• Zmiana formatu logów używanego przez inne systemy (np. SIEM) – z punktu widzenia tych systemów to też API. Może wymagać MAJOR.

Tu wychodzi sedno: semver dotyczy kontraktu z konsumentem, a konsumentem nie zawsze jest tylko klient HTTP. Może nim być system logujący, joby ETL, nawet regex w pipeline’ach zbierających metryki.

Jak zespół rozstrzyga sporne przypadki

Nie istnieje jedna „obiektywna” odpowiedź dla każdego przypadku. Liczy się spójność w ramach jednego projektu/organizacji. Można przyjąć prostą zasadę:

• jeśli zmiana może złamać cokolwiek po stronie konsumenta – MAJOR,
• jeśli konsument może się obyć bez zmian, ale ma nowe możliwości – MINOR,
• jeśli konsument nie musi nic wiedzieć, a zachowanie pozostaje takie samo – PATCH.

Dobrym nawykiem jest dokumentowanie takich zasad w krótkim dokumencie „polityka semver” w repo. Nie po to, by debatować godzinami nad każdym release’em, tylko żeby w typowych sytuacjach nie odkrywać koła na nowo.

Pre-release i build metadata: alpha, beta, rc i spółka

Semver pozwala dopisać do wersji prerelease i build metadata:

• pre-release: 1.4.0-alpha.1, 1.4.0-beta.3, 1.4.0-rc.2,
• build metadata: 1.4.0+001, 1.4.0+sha.abc123.

Reguły są dwa kluczowe:

• wersja z sufiksem pre-release (1.4.0-beta.1) jest zawsze „mniejsza” niż odpowiadająca jej wersja stabilna (1.4.0) i nie powinna zastępować jej na produkcji,
• build metadata (część po +) nie wpływa na porządek wersji – służy wyłącznie do identyfikacji builda, analizy i debugowania.

Typowy, bezpieczny schemat w CI wygląda tak: gałąź main generuje stabilne wersje 1.5.0, 1.5.1 itd., a gałęzie feature’owe lub release candidate’y oznaczasz jako 1.6.0-alpha.5, 1.6.0-rc.1. Te drugie mogą trafiać na środowiska testowe lub do wybranych klientów, ale narzędzia deployujące nie powinny ich brać „przypadkiem” zamiast stabilnych. Typowy błąd: zarejestrowanie w registry obrazu 1.6.0-rc.1 z tagiem latest i automatyczne podciągnięcie go na produkcję.

Mitem jest przekonanie, że pre-release to tylko kosmetyczny dopisek dla marketingu. W praktyce to bardzo proste, binarne rozróżnienie: czy konsument może oczekiwać stabilności kontraktu, czy nie. Jeśli obiecujesz integratorom stabilne API, a jednocześnie wypuszczasz na wspólny cluster wersje -beta bez wyraźnej separacji, semver na etykiecie niewiele daje – systemy integracyjne i tak dostaną w twarz nieprzewidzianą zmianą.

Build metadata bywa z kolei ignorowana lub nadużywana. Zamiast wciskać hash commita w sam numer wersji (np. 1.5.0-abc123, co łamie semver), lepiej użyć poprawnej formy 1.5.0+sha.abc123 i dodatkowo zapisać ten hash w labelach Dockera czy adnotacjach Kubernetesa. Dzięki temu zachowujesz czytelne semver dla ludzi i maszyn, a jednocześnie masz precyzyjny trop do konkretnego builda, gdy trzeba odtworzyć błąd lub porównać konfigurację środowisk.

Najczęstszy błąd kończący się bałaganem to mieszanie porządków: trochę wersji z pliku, trochę z taga, trochę z -SNAPSHOT, a na deser przyklejony latest. Jeśli semver, tagi i release notes mają cokolwiek ułatwić, jeden system numeracji musi wygrać, być egzekwowany w CI/CD i konsekwentnie przełożyć się na wszystkie artefakty, które lądują na produkcji.

Strategie automatyzacji wersji: od ręcznego bumpa do pełnego auto-release

Ręczne podbijanie wersji z lekką automatyzacją

Najprostszy, ale wciąż sensowny model to ręczne decydowanie o wersji, a automatyczne egzekwowanie konsekwencji w CI.

Typowy przepływ wygląda tak:

1. Programista lub release manager decyduje: „to będzie 1.8.0” (np. bo pojawiło się kilka nowych funkcji zgodnych wstecznie).
2. Robi commit z podbiciem wersji w pliku (np. VERSION lub package.json).
3. Tworzy anotowany tag Git v1.8.0 na tym commicie.
4. Pipeline CI reaguje na tag:
   • weryfikuje, że wersja w pliku = wersja w tagu,
   • buduje artefakty z wersją 1.8.0,
   • publikuje release notes na podstawie commitów od poprzedniego taga.

Mit: „ręczne podbijanie wersji = chaos”. Rzeczywistość: jeśli źródło prawdy jest jedno (tag) i pipeline pilnuje spójności, ręczny krok dotyczy tylko decyzji jaki typ zmiany (MAJOR/MINOR/PATCH), a nie kopiuj-wklej numerków po całym projekcie.

Taki model dobrze działa w mniejszych zespołach lub tam, gdzie release jest świadomą decyzją biznesową, a nie efektem każdego mergowania do main.

Automatyczny dobór wersji na podstawie commitów

Krok dalej to systemy typu conventional commits i narzędzia pokroju semantic-release, release-please czy wtyczki do Gradle/Maven. Zasada jest prosta: typy commitów mapują się na typ wydania.

Przykładowy schemat:

• feat: → MINOR,
• fix: → PATCH,
• feat!: ... lub commit z frazą BREAKING CHANGE: → MAJOR,
• chore:, docs:, refactor: bez wpływu na kontrakt → brak bumpa lub PATCH, zależnie od polityki.

Pipeline wykonujący auto-release może robić w skrócie:

1. Sprawdzić commity od ostatniego taga semver.
2. Wyznaczyć najwyższy wymagany poziom bumpa (np. jest feat i fix, więc MINOR).
3. Wygenerować nowy numer wersji (np. z 1.7.3 → 1.8.0).
4. Utworzyć tag v1.8.0 i release notes na podstawie commitów.
5. Zbudować i opublikować artefakty.

Plus jest oczywisty: zespół nie zastanawia się nad numerkiem przy każdym merge’u, a tylko nad tym, czy commit jest feat, czy fix oraz czy niesie breaking change. Minusem jest to, że jeśli konwencja commitów jest olewana, system będzie zgadywał niewłaściwe wersje albo odmówi wydania.

Częsty zgrzyt: „nie chcemy, żeby każda drobna zmiana frontendu generowała nową wersję biblioteki backoffice”. Tu pomaga rozdzielenie pipeline’ów per komponent i pilnowanie, by auto-release odpalany był tylko tam, gdzie naprawdę mamy niezależny artefakt.

Gałęzie release i automatyczne pre-release’y

W projektach z bardziej formalnym cyklem wydawniczym sprawdza się mieszanka semver + gałęzie release/* + pre-release’y.

Przykład przepływu:

• Zmiany trafiają na develop lub main i generują wersje rozwojowe, np. 1.9.0-alpha.N, publikowane tylko na środowiska testowe.
• Gdy funkcjonalności na iterację są gotowe, tworzysz gałąź release/1.9.0.
• Pipeline dla tej gałęzi:
  • automatycznie nadaje kolejne 1.9.0-rc.1, 1.9.0-rc.2,
  • udostępnia je na środowisku UAT/Stage,
  • zbiera feedback i poprawki jako kolejne -rc.
• Po akceptacji RC:
  • tworzony jest tag v1.9.0 na tej gałęzi,
  • pipeline buduje stabilne artefakty 1.9.0 i markuje je jako „production-ready”.

Mit: „pre-release’y komplikują wersjonowanie”. W praktyce je upraszczają, bo dają wyraźny kordon: wszystko z sufiksem -alpha/-beta/-rc jest testowe, wszystko bez sufiksu – stabilne. Narzędzia deployujące mogą wtedy mieć bardzo prostą regułę wyboru wersji na środowisko.

Minimalna checklista dla automatycznego wersjonowania

Przed włączeniem auto-bumpa i auto-release’u dobrze domknąć kilka decyzji. Krótka lista kontrolna ułatwia uniknięcie efektu „żyje własnym życiem”:

• Czy ustalony jest jeden format commitów lub sposób sygnalizowania breaking change’ów?
• Czy jasne jest, z którego brancha powstają stabilne releasy, a z których tylko pre-release’y?
• Czy pipeline blokuje publikację artefaktów bez poprawnego taga semver lub spójnej wersji w pliku/tagu?
• Czy registry (Docker, Maven, npm) nie nadpisuje wersji (brak force push na istniejące 1.2.3)?
• Czy „latest” jest wyłącznie aliasem do ostatniej stabilnej wersji, a nie do dowolnego builda?

Każdy z powyższych punktów, pozostawiony „na potem”, wcześniej czy później kończy się zagadką: „czemu na Stage jest coś innego niż na produkcji, mimo że numery wyglądają podobnie?”.

Wersjonowanie różnych typów artefaktów: obrazy Docker, paczki, helm charty

Obrazy Docker: semver w tagach i labelach

Docker kusi prostotą tagów, co szybko prowadzi do legendarnego latest. Bardziej przewidywalny schemat to:

• główny tag semver: app:1.4.2,
• aliasy dla wygody: app:1.4 (ostatni patch z danej linii), app:1 (ostatni minor z danej linii),
• opcjonalny app:latest wskazujący tylko na najnowszą stabilną wersję, nigdy na alpha/beta/rc,
• pre-release’y jako osobne tagi: app:1.5.0-rc.1, app:1.5.0-beta.2.

Do tego dochodzą label’e OCI, np.:

LABEL org.opencontainers.image.version="1.4.2" 
      org.opencontainers.image.revision="abc1234" 
      org.opencontainers.image.source="https://git.example.com/org/repo"

Ta kombinacja rozwiązuje dwa problemy naraz: system deployujący wybiera obraz po czytelnym tagu semver, a w razie potrzeby łatwo sprawdzić, z jakiego commita i repo powstał artefakt.

Klasyczny scenariusz awarii to „cichy retag”: ktoś nadpisuje app:1.4.2 nowym buildem. Jeśli registry na to pozwala, produkcja zaczyna zachowywać się inaczej przy tym samym numerze wersji. Realna obrona to polityka „no overwrite” w registry + zakaz retagowania istniejących wersji w pipeline.

Biblioteki i paczki: wersja jako część kontraktu

Dla bibliotek (Java, .NET, npm, PyPI) semver jest wręcz elementem protokołu: konsument deklaruje, z jakim zakresem wersji daje się pracować.

Przykłady:

• npm: "^1.4.0" → akceptuj 1.x.x, ale nie 2.0.0,
• Maven: [1.4.0,2.0.0) → to samo w innym zapisie.

Mit: „u nas i tak wszyscy biorą najnowszą wersję biblioteki, semver nie ma znaczenia”. Dopóki nie ma kilku niezależnych konsumentów, to może działać. Kiedy jednak jedna biblioteka jest używana przez więcej niż jeden zespół, numer wersji staje się jedynym sensownym sposobem komunikacji ryzyka: czy update jest bezpieczny z automatu (PATCH), czy trzeba przeczytać release notes i sprawdzić migrację (MAJOR).

W pipeline dla paczek bibliotecznych sensowny jest prosty wzorzec:

1. Tag Git semver uruchamia build.
2. Build weryfikuje, że:
   • wersja w pliku konfiguracyjnym (np. pom.xml, package.json) jest identyczna,
   • w rejestrze nie istnieje jeszcze taka wersja (brak nadpisywania).
3. Artefakt ląduje w rejestrze dokładnie pod tą wersją – bez dodatkowych dopisków typu -SNAPSHOT dla stabilnych release’ów.

Jeśli potrzebne są snapshoty, ich miejsce jest w osobnym repozytorium lub z wyraźnym sufiksem (1.5.0-SNAPSHOT) i regułami, że środowiska produkcyjne po nie nie sięgają.