Git Commit Messages: Formatowanie 50/72

Tim Pope opowiada się za szczególnym stylem wiadomości Git commit w swoim blogu: http://www.tpope.net/node/106 .

Oto krótkie podsumowanie tego, co poleca:

• Pierwszy wiersz ma 50 znaków lub mniej.
• Następnie pusta linia.
• Pozostały tekst powinien być zawinięty w 72 znaki.

Jego post na blogu zawiera uzasadnienie dla tych zaleceń (które nazywam „formatowaniem 50/72” dla zwięzłości):

• W praktyce niektóre narzędzia traktują pierwszy wiersz jako wiersz tematu, a drugi akapit jako treść (podobnie jak w wiadomości e-mail).
• git log nie obsługuje zawijania, więc trudno jest odczytać, jeśli linie są za długie.
• git format-patch --stdout konwertuje commity na e-mail - więc granie w fajne pomaga, jeśli twoje commity są już ładnie opakowane.

Chciałbym dodać, że myślę, że Tim zgodziłby się z:

• Podsumowanie zatwierdzenia jest dobrą praktyką nieodłącznie związaną z każdym systemem kontroli wersji. Pomaga innym (lub późniejszym) szybciej znaleźć odpowiednie zatwierdzenia.

Mam więc kilka pytań do mojego pytania:

• Jaka część (z grubsza) „liderów myśli” lub „doświadczonych użytkowników” Gita przyjmuje styl formatowania 50/72? Pytam o to, ponieważ czasami nowi użytkownicy nie znają praktyk społecznościowych lub nie dbają o nie.
• Czy dla tych, którzy nie używają tego formatowania, istnieje zasadny powód, aby używać innego stylu formatowania? (Pamiętaj, że szukam argumentu merytorycznego, a nie „Nigdy o nim nie słyszałem” ani „Nie dbam o to”).
• Z empirycznego punktu widzenia, jaki procent repozytoriów Git obejmuje ten styl? (Jeśli ktoś chce przeprowadzić analizę repozytoriów GitHub… wskazówka, wskazówka).

Nie chcę tutaj polecać stylu 50/72 ani zestrzelić innych stylów. (Mówiąc otwarcie, wolę to, ale jestem otwarty na inne pomysły.) Chcę tylko uzyskać uzasadnienie, dlaczego ludzie lubią różne style wiadomości Git. (Zachęcamy również do przywołania punktów, o których jeszcze nie wspomniano).

W odniesieniu do wiersza „podsumowanie” (50 w formule) dokumentacja jądra Linuksa ma następującą treść :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

To powiedziawszy, wygląda na to, że opiekunowie jądra rzeczywiście starają się utrzymać około 50. Oto histogram długości linii podsumowania w dzienniku git dla jądra:

( zobacz w pełnym rozmiarze )

Istnieje odrobina zatwierdzeń, które mają linie podsumowania, które są dłuższe (niektóre znacznie dłuższe), niż ten wykres może pomieścić, bez powodowania, że ​​interesująca część wygląda jak jedna linia. (Prawdopodobnie jest jakaś wymyślna technika statystyczna do włączenia tych danych tutaj, ale cóż… :-)

Jeśli chcesz zobaczyć nieprzetworzone długości:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

lub histogram tekstowy:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

W odniesieniu do „liderów myśli”: Linus zdecydowanie opowiada się za zawijaniem wierszy dla pełnego komunikatu zatwierdzenia:

[…] Używamy 72-znakowych kolumn do zawijania tekstu, z wyjątkiem cytowanego materiału, który ma określony format wiersza.

Wyjątki odnoszą się głównie do tekstu „bez prozy”, to znaczy tekstu, który nie został wpisany przez człowieka do zatwierdzenia - na przykład komunikaty o błędach kompilatora.

Rozdzielenie prezentacji i danych napędza moje komunikaty zatwierdzania tutaj.

Komunikat zatwierdzenia nie powinien być zawijany na sztywno przy żadnej liczbie znaków, a zamiast tego należy używać podziałów linii do oddzielania myśli, akapitów itp. Jako części danych, a nie prezentacji. W tym przypadku „dane” to komunikat, który próbujesz przekazać, a „prezentacja” to, jak widzi to użytkownik.

Używam jednego wiersza podsumowania u góry i staram się go skracać, ale nie ograniczam się do dowolnej liczby. Byłoby znacznie lepiej, gdyby Git rzeczywiście zapewniał sposób przechowywania wiadomości podsumowujących jako osobnej jednostki od wiadomości, ale ponieważ tak nie jest, muszę włamać się do niej i jako separatora używam podziału pierwszego wiersza (na szczęście wiele narzędzi obsługuje oznacza to rozbicie danych).

Dla samej wiadomości nowe linie wskazują coś znaczącego w danych. Pojedyncza nowa linia oznacza początek / przerwę na liście, a podwójna nowa linia oznacza nową myśl / pomysł.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Oto jak to wygląda w przeglądarce, która miękko otacza tekst.

To jest linia podsumowania, postaraj się, aby była krótka i kończyła się łamaniem linii.

To jest myśl, być może wyjaśnienie tego, co zrobiłem w czytelnym dla człowieka formacie. Może być złożony i długi, składający się z kilku zdań opisujących moją pracę w formie eseju. Nie do mnie należy teraz decydowanie (w czasie autora), w jaki sposób użytkownik zamierza wykorzystać te dane.

Dwie przerwy między wierszami oddzielają te dwie myśli. Użytkownik może czytać to na telefonie lub monitorze szerokiego ekranu. Czy próbowałeś kiedyś przeczytać tekst zawinięty w 72 znaki na urządzeniu, które wyświetla tylko 60 znaków? To naprawdę bolesne doświadczenie. Także zdanie otwierające ten akapit (zakładając format stylu eseju) powinno być wstępem do akapitu, więc jeśli narzędzie wybierze, może nie chcieć automatycznie zawijać i pozwalać zobaczyć tylko początek każdego akapitu. Ponownie, to narzędzie prezentacji nie jest mną (przypadkowym autorem w pewnym momencie historii), aby spróbować zmusić moje konkretne formatowanie do gardła wszystkich innych.

Jako przykład, oto lista punktów:
* Punkt 1.
* Punkt 2.
* Punkt 3.

Podejrzewam, że autor rekomendacji Git, do której linkujesz, nigdy nie napisał oprogramowania, które będzie używane przez szeroką gamę użytkowników końcowych na różnych urządzeniach wcześniej (tj. Na stronie internetowej), ponieważ na tym etapie ewolucji oprogramowania / komputerów dobrze wiadomo, że przechowywanie danych z zakodowanymi informacjami prezentacji jest złym pomysłem, jeśli chodzi o wrażenia użytkownika.

Zgadzam się, że interesujące jest zaproponowanie określonego stylu pracy. Jednak chyba, że ​​mam okazję ustawić styl, zwykle podążam za tym, co zostało zrobione dla zachowania spójności.

Patrząc na Linux Jern Commits, projekt, który zaczął git, jeśli chcesz, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , nie przestrzegają zasady 50/72. Pierwszy wiersz ma 54 znaki.

Powiedziałbym, że spójność ma znaczenie. Skonfiguruj odpowiednie sposoby identyfikacji użytkowników, którzy dokonali zatwierdzeń (nazwa.użytkownika, nazwa.użytkownika - szczególnie w sieciach wewnętrznych. Użytkownik @ OFFICE-1-PC-10293982811111 nie jest przydatnym adresem kontaktowym). W zależności od projektu udostępnij odpowiednie szczegóły w zatwierdzeniu. Trudno powiedzieć, co to powinno być; mogą to być zadania ukończone w procesie programowania, a następnie szczegóły zmian.

Nie sądzę, że użytkownicy powinni używać git w jeden sposób, ponieważ niektóre interfejsy do git traktują zatwierdzenia w określony sposób.

Powinienem też zauważyć, że istnieją inne sposoby na znalezienie zatwierdzeń. Na początek git diffpowie ci, co się zmieniło. Możesz także robić takie rzeczy, jak git log --pretty=format:'%T %cN %ce'formatowanie opcji git log.

Czy maksymalna zalecana długość tytułu to naprawdę 50?

Wierzyłem w to od lat, ale jak właśnie zauważyłem, dokumentacja „git commit” faktycznie mówi

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

Można argumentować, że „mniej niż 50” może oznaczać „nie dłużej niż 49”.