Generator Conventional Commit

Generator Conventional Commit — czytelna wiadomość zgodna ze standardem

Generator Conventional Commit układa wiadomość commita w przewidywalnym formacie typ(zakres): opis. Wybierasz rodzaj zmiany, opcjonalny zakres i krótki opis, a następnie możesz dodać rozwinięcie, informację BREAKING CHANGE oraz odwołania do zgłoszeń. Wynik nadaje się do wklejenia w Git i do przetwarzania przez narzędzia budujące changelog lub wersję wydania.

Dlaczego format wiadomości ma znaczenie

Historia repozytorium jest dokumentacją decyzji technicznych. Gdy każdy autor zapisuje zmianę inaczej, trudno odróżnić nową funkcję od naprawy, znaleźć obszar aplikacji albo przygotować listę zmian dla użytkowników. Conventional Commits wprowadza mały, łatwy do zapamiętania kontrakt. Pierwszy token określa intencję, zakres wskazuje moduł, a opis mówi, co zmienia commit. Taki zapis jest czytelny podczas code review i jednocześnie możliwy do jednoznacznego przetworzenia przez automat.

Budowa nagłówka, treści i stopki

feat(auth): dodaj logowanie kluczem dostępu

Obsłuż uwierzytelnianie w aplikacji mobilnej.

BREAKING CHANGE: usuń poprzedni format tokenu

Refs: #123

Nagłówek powinien być krótki i samodzielny. Typ jest obowiązkowy, zakres pozostaje opcjonalny, a wykrzyknik po zakresie sygnalizuje zmianę niekompatybilną. Po pustej linii można dodać treść wyjaśniającą powód i skutki. Stopki służą między innymi do opisania breaking change oraz połączenia commita ze zgłoszeniem. Generator pilnuje, aby dane nagłówka i numer zgłoszenia nie mogły wstrzyknąć dodatkowej linii do gotowej wiadomości.

Typy feat, fix i pozostałe kategorie

Zakres, opis i limit długości

Zakres, nazywany scope, powinien być stabilną nazwą części systemu, na przykład auth, api, checkout lub docs. Nie wpisuj w nim numeru zadania ani pełnego zdania. Opis najlepiej formułować w trybie rozkazującym: „dodaj walidację”, „napraw sortowanie”, „usuń przestarzałą opcję”. Generator liczy cały nagłówek, czyli także typ, nawiasy i zakres. Przekroczenie wybranego limitu nie usuwa wyniku, lecz jest wyraźnie sygnalizowane, aby autor mógł świadomie skrócić tekst.

BREAKING CHANGE i wersjonowanie semantyczne

Zmiana łamiąca kompatybilność wymaga uwagi niezależnie od tego, czy jej typem jest feat, fix czy refactor. Zaznaczenie opcji dodaje ! w nagłówku i stopkę BREAKING CHANGE:. W stopce opisz, co przestaje działać oraz jak przeprowadzić migrację. Narzędzia zgodne z SemVer mogą mapować fix na patch, feat na minor, a breaking change na major. Sam komunikat nie publikuje jednak wersji — reguły wydawania określa konfiguracja projektu i pipeline, który można przygotować w generatorze GitLab CI.

Od wiadomości do changeloga i automatyzacji

Spójne commity pozwalają filtrować historię, grupować zmiany według typu i generować release notes bez ręcznego przepisywania listy zadań. Pomagają też egzekwować politykę w hooku commit-msg. Jeśli repozytorium dopiero powstaje, warto równolegle przygotować zasady ignorowania plików w generatorze .gitignore. W projektach z automatycznymi testami komunikaty typu ci i build łatwo połączysz z przepływem utworzonym przez generator GitHub Actions.

Jak zbudować dobrą wiadomość krok po kroku

1. Wybierz typ na podstawie skutku zmiany, a nie nazwy zadania lub gałęzi.
2. Dodaj krótki zakres, jeśli pomaga wskazać moduł; pomiń go, gdy commit dotyczy całego projektu.
3. Napisz jednowierszowy opis w trybie rozkazującym, bez kropki na końcu.
4. W treści wyjaśnij powód, ograniczenia i decyzje, których nie widać z diffu.
5. Zaznacz breaking change tylko wtedy, gdy odbiorca musi zmienić integrację, dane lub konfigurację.
6. Dodaj numery zgłoszeń oddzielone przecinkami, sprawdź długość i skopiuj gotową wiadomość.

Najczęściej zadawane pytania