Najlepsze praktyki dotyczące komunikatów commitów

Proszę wyobrazić sobie przeglądanie historii projektu. Bez jasnych komunikatów commitów przypomina ona czytanie pamiętnika z pustymi wpisami!

Dobre komunikaty commitów mają kluczowe znaczenie dla zrozumienia, dlaczego wprowadzono zmiany, co zostało zmienione i jak zmiany wpływają na projekt. Pomaga to Państwu i zespołowi diagnozować błędy, przeglądać kod oraz wdrażać nowych członków zespołu.

Standardowy komunikat commita Git składa się z dwóch głównych części:

• Temat: Pojedynczy, zwięzły wiersz podsumowujący zmianę.
• Treść (opcjonalna): Bardziej szczegółowe wyjaśnienie oddzielone od tematu pustym wierszem.

Można porównać to do wiadomości e-mail: temat ułatwia szybkie przejrzenie, a treść zawiera szczegóły.

Temat jest najważniejszą częścią komunikatu. Oto zasady:

• Zwięzłość: Należy ograniczyć go do 50–72 znaków.
• Tryb rozkazujący: Należy rozpocząć od czasownika w czasie teraźniejszym (np. „Add feature”, a nie „Added feature” ani „Adding feature”).
• Wielka pierwsza litera: To standardowa praktyka poprawiająca czytelność.
• Bez kropki: Tematu nie należy kończyć kropką.

Przyjrzyjmy się kilku dobrym i złym tematom:

• Dobry: Fix: broken login button
• Dobry: Feat: implement user profile page
• Zły: Fixed a bug in the login system that was causing issues. (Zbyt długi, w czasie przeszłym)
• Zły: updates (Zbyt ogólny)

Należy dążyć do jasności i zwięzłości!

Treść commita służy do wyjaśnienia motywacji stojącej za zmianą, jej kontekstu oraz wszelkich szczegółów, które nie wynikają bezpośrednio z samego kodu.

Należy jej używać, gdy zmiana wymaga dokładniejszego wyjaśnienia, niż może zapewnić temat. Dla lepszej czytelności w narzędziach Git należy zawijać wiersze po około 72 znakach.

Podczas pisania treści:

• Należy wyjaśnić, dlaczego wprowadzono zmianę, a nie tylko co zmieniono.
• Należy opisać kompromisy i decyzje projektowe.
• Należy wspomnieć o potencjalnych skutkach ubocznych lub obszarach wymagających obserwacji.
• Należy pozostawić pusty wiersz między tematem a treścią.

Zapewnia to cenny kontekst dla osób, które będą czytać komunikat w przyszłości.

Oto przykład pełnego, dobrze uporządkowanego komunikatu commita:

Wiele zespołów przyjmuje konwencję, zgodnie z którą temat rozpoczyna się od prefiksu typu. Ułatwia to szybkie kategoryzowanie zmian.

Typowe prefiksy to:

• feat: (nowa funkcja)
• fix: (poprawka błędu)
• docs: (zmiana w dokumentacji)
• style: (styl kodu, bez zmiany funkcjonalności)
• refactor: (refaktoryzacja kodu)
• test: (dodawanie testów)
• chore: (utrzymanie projektu, zmiany w procesie budowania)

Dobrą praktyką jest łączenie commitów z powiązanymi issue lub pull requestami w systemie zarządzania projektem (np. GitHub Issues lub Jira).

Można to zrobić, umieszczając w komunikacie commita, zwykle w treści, wyrażenia takie jak Closes #123, Fixes #45 lub Refs #67. Spowoduje to automatyczne połączenie zmian w kodzie ze śledzonym zadaniem.

Jakie z poniższych cech charakteryzują dobrze napisany komunikat commita Git zgodnie z najlepszymi praktykami?

Dowiedzieli się już Państwo, że dobrze przygotowane komunikaty commitów mają kluczowe znaczenie dla przejrzystości projektu i współpracy. Stosowanie tych najlepszych praktyk sprawia, że historia projektu staje się cennym źródłem informacji!

• Tematy powinny być zwięzłe i zapisane w trybie rozkazującym.
• Treść powinna wyjaśniać, „dlaczego” wprowadzono zmianę.
• Warto rozważyć używanie prefiksów typów do kategoryzowania zmian.
• Dla zapewnienia kontekstu należy dodawać odwołania do issue lub pull requestów.

Udanych commitów!