Konwencje commitów (Conventional Commits)
Po co konwencja w opisach commitów
Opis commita to wiadomość do przyszłości — do Ciebie i zespołu za pół roku. Conventional Commits to prosty standard, który nadaje opisom strukturę, dzięki czemu historia jest czytelna, a narzędzia mogą z niej generować changelogi i numery wersji.
Format
<typ>(<zakres opcjonalny>): <opis>
<opcjonalne ciało>
<opcjonalna stopka>
Przykłady:
feat(dashboard): dodaj widżet MFA
fix(auth): popraw redirect po wygaśnięciu sesji
docs(readme): uzupełnij instrukcję deployu
refactor(api): wydziel walidację do osobnej funkcji
Typy commitów
| Typ | Znaczenie |
|---|---|
feat | Nowa funkcjonalność |
fix | Poprawka błędu |
docs | Tylko dokumentacja |
style | Formatowanie, bez zmiany logiki |
refactor | Zmiana kodu bez nowej funkcji ani fixa |
test | Dodanie/poprawa testów |
chore | Konfiguracja, zależności, narzędzia |
ci | Zmiany w pipeline CI/CD |
perf | Optymalizacja wydajności |
Powiązanie z wersjonowaniem (SemVer)
Typy mapują się na semantyczne wersjonowanie:
fix:→ podbicie PATCH (1.2.3 → 1.2.4)feat:→ podbicie MINOR (1.2.3 → 1.3.0)- BREAKING CHANGE → podbicie MAJOR (1.2.3 → 2.0.0)
Zmianę łamiącą zgłaszasz przez ! lub stopkę:
feat(api)!: zmień format odpowiedzi raportów
BREAKING CHANGE: pole "total" zwraca teraz wartość netto zamiast brutto.
Wskazówka: Opis pisz w trybie rozkazującym, jakbyś dokończył zdanie "Ten commit, jeśli go zastosujesz, …": "dodaj X", "popraw Y" — nie "dodałem", "dodaje". To konwencja zgodna z samym Gitem.
Egzekwowanie konwencji w CI
Można sprawdzać format automatycznie. Lokalnie poprzez hook commitlint, a w pipeline jako krok GitHub Actions:
name: Lint commits
on: [pull_request]
jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: wagoid/commitlint-github-action@v6
Dobre nawyki
- Jeden commit = jedna logiczna zmiana.
- Pierwsza linia ≤ ~72 znaki, bez kropki na końcu.
- W ciele commita wyjaśnij dlaczego, nie tylko co (to widać w diffie).
- Zakres (
dashboard,auth) ułatwia przeszukiwanie historii.
Korzyść końcowa
Spójne commity pozwalają narzędziom typu release-please czy
semantic-release automatycznie tworzyć changelog i tagować wersje na
podstawie samej historii — zero ręcznego pisania release notes.
Podsumowanie
Conventional Commits to mały koszt i duża wygoda: typ(zakres): opis w trybie
rozkazującym. Typy mapują się na SemVer, a CI z commitlintem pilnuje formatu.
Efekt to czytelna historia i automatyczne changelogi.