Jak napisać skuteczną, użyteczną wiadomość Git Commit

Komunikaty o zatwierdzeniu to krótkie opisy każdego zatwierdzenia w systemie kontroli wersji, takim jak Git. Kiedy zatwierdzasz zmiany w plikach projektu, powinieneś podać komunikat wyjaśniający, co robią lub dlaczego je wprowadziłeś.

Komunikaty Commit służą jako forma dokumentacji i komunikacji. Odgrywają kluczową rolę w utrzymaniu przejrzystej i zorganizowanej historii wersji projektu. Naucz się pisać dobre komunikaty dotyczące zatwierdzeń, a pozostali członkowie Twojego zespołu jeszcze bardziej docenią Twoją pracę.

Struktura komunikatu o dobrym zobowiązaniu

Dobry przykład komunikatu zatwierdzenia zawiera cztery sekcje: Typ, Opis, Treść i Stopka.

jak tak:

: 
[opcjonalne ciało]
[opcjonalna stopka]

Typ

Typ opisuje rodzaj zmiany dokonanej w bieżącym zatwierdzeniu. Możesz użyć dowolnego systemu, który ma sens w twoich okolicznościach. Na przykład, oto kilka przykładowych słów kluczowych, których możesz użyć do zasygnalizowania każdego rodzaju zmiany, wraz z przykładowym użyciem:

• wyczyn: Twoje zmiany wprowadzają nową funkcję.
• naprawić: naprawiasz błąd.
• refaktoryzacja: Twój kod refaktoryzacji zmian bez naprawiania błędu lub dodawania nowej funkcji.
• test: wprowadzasz wszelkie zmiany związane z testowaniem. Na przykład, kiedy ty pisać testy z Jest lub jakikolwiek inne środowisko testowe Ty wybierasz.
• obowiązek: zmiany niezwiązane z poprawką, funkcją lub testem. Na przykład aktualizowanie zależności.
• dokumenty: podczas aktualizacji dokumentacji.
• styl: zmiany, które nie wpływają na znaczenie kodu, takie jak dodanie spacji, brak średników itp.
• wyk: zmiany związane z ulepszeniami wydajności.
• zbudować: kiedy wprowadzasz zmiany, które mają wpływ na pliki kompilacji.
• ci: zmiany związane z ciągłą integracją.
• Odwracać: przy powrocie do poprzedniego zatwierdzenia.

Opis

„Opis” komunikatu zatwierdzenia jest zwięzłym i opisowym podsumowaniem zmian dokonanych w zatwierdzeniu. Służy jako nagłówek, który oddaje istotę zatwierdzenia.

Pisząc opis, pamiętaj o następujących kwestiach:

• Spraw, aby był wystarczająco jasny i konkretny, aby szybko opisać zatwierdzenie.
• Zrób to krótko i zwięźle. Najlepiej byłoby ograniczyć go do 50 znaków lub mniej.
• Napisz to w czasie teraźniejszym, nawet jeśli opisujesz już dokonane zmiany.
• Używaj trybu rozkazującego podczas pisania.
• Zacznij od dużej litery.
• Nie kończ tego okresem.

Na przykład:

wyczyn: Zaimplementuj przełączanie trybu ciemnego na stronie głównej

Ten przykład pokazuje, w jaki sposób można napisać opis zatwierdzenia implementuje tryb ciemny. Używa wyczyn typu, ponieważ wprowadza nową funkcję.

Ciało (opcjonalnie)

Sekcja treści komunikatu zatwierdzenia zawiera dodatkowe szczegóły i kontekst zmian wprowadzonych w zatwierdzeniu. Nie zawsze będziesz potrzebować ciała, ale może ono pomóc w dostarczeniu większej ilości informacji, wyjaśnieniu uzasadnienia zmiany lub opisaniu wszelkich kwestii technicznych.

Oto kilka rzeczy, na które należy zwrócić uwagę podczas pisania sekcji treści wiadomości zatwierdzenia:

• Git nigdy nie zawija tekstu automatycznie, więc ręcznie zawijaj go do 72 znaków podczas pisania treści. Daje to Gitowi wystarczająco dużo miejsca na wcięcie tekstu, czyniąc go bardziej czytelnym.
• Użyj ciała, aby wyjaśnić, co się stało podczas zmiany, dlaczego dokonałeś zmiany i uzasadnij swoją zmianę.
• Musisz zostawić pustą linię między linią opisu a treścią. Dzięki temu Git może je rozróżnić.
• Jeśli zatwierdzenie wprowadza wiele zmian lub wpływa na różne obszary bazy kodu, rozważ użycie punktorów lub akapitów w celu rozbicia modyfikacji. Poprawia to czytelność i pomaga czytelnikom zrozumieć różne aspekty zatwierdzenia.

Na przykład:

wyczyn: Dodaj GitHub jako dostawcę OAuth
Zintegruj GitHub jako dostawcę OAuth, aby zapewnić płynność 
uwierzytelnianie za pomocą kont GitHub.
- Zaimplementuj przepływ uwierzytelniania OAuth za pomocą GitHub API
- Skonfiguruj niezbędne punkty końcowe i ustawienia uwierzytelniania GitHub
— Zaktualizowano interfejs użytkownika, aby zawierał opcję logowania GitHub

Powyższy przykład pokazuje dobry komunikat zatwierdzenia Git dla funkcji, która dodaje GitHub jako dostawca OAuth do Twojej aplikacji. Ta wiadomość zatwierdzenia zawiera zwięzły wiersz podsumowania (50 znaków lub mniej), bardziej szczegółowy tekst wyjaśniający (zawinięty do około 72 znaków) oraz wypunktowania zawierające dodatkowe informacje.

Sekcja stopki w komunikacie zatwierdzenia jest opcjonalną częścią, która zawiera dodatkowe informacje lub metadane związane z zatwierdzeniem. Zwykle umieszcza się go za sekcją ciała, oddzieloną pustą linią. Stopka może zawierać różnego rodzaju informacje, takie jak odniesienia do powiązanych zagadnień, tagi czy uwagi specjalne.

Odwołując się do problemów, żądań ściągnięcia lub innych powiązanych elementów, użyj odpowiedniej składni lub formatu wymaganego przez system śledzenia problemów Twojego projektu. Zapewnia to prawidłowe rozpoznanie i powiązanie odnośników.

Na przykład:

wyczyn: Dodaj GitHub jako dostawcę OAuth
Zintegruj GitHub jako dostawcę OAuth, aby zapewnić płynność 
uwierzytelnianie za pomocą kont GitHub.
- Zaimplementuj przepływ uwierzytelniania OAuth za pomocą GitHub API
- Skonfiguruj niezbędne punkty końcowe i ustawienia uwierzytelniania GitHub
— Zaktualizowano interfejs użytkownika, aby zawierał opcję logowania GitHub
Rozwiązanie: #123
Zobacz też: #456, #789

Stopka odnosi się do powiązanego problemu nr 123 i wymienia inne powiązane problemy nr 456 i 789 w celu uzyskania dodatkowego kontekstu.

Dodanie komunikatu o zatwierdzeniu

Możesz pisać komunikaty zatwierdzenia za pomocą -M flaga, po której następuje komunikat zatwierdzenia ujęty w cudzysłowy (opcjonalny, ale zalecany).

The -M flaga jest idealna dla krótkich komunikatów zatwierdzenia, zwykle zawierających typ i opis.

Na przykład:

git commit -m "obowiązek: Zmień linter na ESlint"

Jeśli jednak wiadomość zatwierdzenia wymaga więcej szczegółów, takich jak treść i stopka, lepiej napisać zatwierdzenie w edytorze tekstu lub środowisku IDE.

Alternatywnie możesz napisać długie komunikaty zatwierdzenia w pliku tekstowym i użyć --plik flag, aby określić komunikaty zatwierdzenia jako zawartość pliku tekstowego.

Na przykład:

git commit --file commit_message.txt

Gdy uruchomisz powyższą komendę, git użyje zawartości pliku jako komunikatu zatwierdzenia.

Możesz także powiedzieć gitowi, aby otworzył domyślny edytor i napisał dłuższą wiadomość. Jeśli masz ustawioną zmienną środowiskową GIT_EDITOR lub EDITOR, git otworzy ten program, gdy uruchomisz gołe git zatwierdzenie Komenda.

Dlaczego warto pisać dobre komunikaty o zobowiązaniach

Pisanie dobrych komunikatów dotyczących zatwierdzeń ma kluczowe znaczenie dla efektywnej współpracy i utrzymania kodu. Jasne i opisowe komunikaty ułatwiają zrozumienie, debugowanie i przeglądy kodu. Mogą nawet współtworzyć dokumentację projektową lub informacje o wydaniu.

Umożliwiają dzielenie się wiedzą, płynne wdrażanie i wspierają kontrolę wersji. Priorytetyzacja komunikatów o zatwierdzeniu jakości usprawnia procesy programistyczne i zapewnia łatwość konserwacji bazy kodu.