Git commit – o sztuce opisania co się zrobiło

Dobry opis dodany do commita to najlepszy sposób na przekazanie informacji do wprowadzonych zmian.

Git commit to nie tylko zatwierdzenie zmian w kodzie to także możliwość wysłania informacji, która może okazać się pomocna dla  innych osób pracująca nad projektem lub dla nas samych. Dobry opis dodany do commita to najlepszy sposób na przekazanie informacji do wprowadzonych zmian. Można by to ująć takimi słowami: “porównanie zmian w kodzie pokaże Ci co się zmieniło a opis może powiedzieć dlaczego”.

 

To jak w takim razie to dobrze zrobić? Starajmy się pisać tak, żebyśmy mogli to szybko zrozumieć kilka dni później. Praktyczną rzeczą jest możliwość podzielenia opisu na dwie części – główny skrócony opis oraz opcjonalną część szczegółową. Aby osiągnąć ten efekt, wystarczy obie części oddzielić jedną pustą linią, w gitlabie będzie wyglądać to tak:

Innym praktycznym zabiegiem jest możliwość dodania do otwartego  ticketu lub merge requesta informacji o naszym commicie (wraz z linkiem do niego). Należy w opisie podać numer id poprzedzony znakiem # – dla issue lub ! – dla merge request (np. #123). Dla ticketa pochodzącego z innego projektu, niż ten do którego commitujemy, przykładowy zapis będzie wyglądał tak grupa/nazwaProjekctu#123.  Co więcej jeżeli przed referencją do ticketu dopiszemy fixes lub closes (np closes #123), to kiedy merge request zawierający taki commit zostanie zatwierdzony i trafi do defaultowego brancha (zazwyczaj master) to automatycznie zostanie zamknięty ticket o danym numerze. Co jeszcze można powiedzieć na temat dobrego opisu. W większości przypadków można pominąć szczegół dotyczący zmian w kodzie. Lepiej skupić się na powodach wprowadzonej zmiany, jak działało to wcześniej, jak będzie działać teraz, dlaczego zdecydowaliśmy się na zmianę.

 

Dla podsumowania kilka zaleceń dla dobrego opisu commita:

  1. Oddziel wiersz tematu od opisu jedną pustą linią.
  2. Wiersz temat nie powinien być dłuższy niż 50 znaków.
  3. Rozpocznij wielką literą, nie stawiaj kropki na końcu pierwszej linii.
  4. Każda linia w ciele opisu nie powinna przekraczać 72 znaków.
  5. Dopisuj numer ticketa jeżeli commit go dotyczy.
  6. W ciele opisu napisz co i dlaczego.

Żródła:

How to Write a Git Commit Message  

Jak powinien wyglądać dobry commit?

https://about.gitlab.com/2016/03/08/gitlab-tutorial-its-all-connected/

Autor: Paweł Mańkiewicz


Opublikowano:

Mentax na Facebook'u