Czy powinienem używać czasu przeszłego czy teraźniejszego w komunikatach git commit? [Zamknięte]

I czytać po tym git commit wiadomości powinny być imperatywem teraźniejszym, np „Dodaj testy dla x”. Zawsze używam czasu przeszłego, np. „Dodane testy dla x”, co wydaje mi się bardziej naturalne.

Oto ostatnie zatwierdzenie Johna Resiga pokazujące wiadomość dwa w jednym:

Popraw kilka wyników jQuery w testach manipulacji. Poprawiono również kolejność oczekiwanych wyników testu.

Czy to ma znaczenie? Z którego powinienem korzystać?

Preferencje dotyczące czasowych komunikatów zatwierdzania w stylu imperatywnym pochodzą od samego Git. Z dokumentacji / przesyłania zgłoszeń w repozytorium Git:

Opisz swoje zmiany w trybie rozkazującym, np. „Make xyzzy do frotz” zamiast „[Ta łatka] sprawia, że ​​xyzzy do frotz” lub „[I] zmieniłem xyzzy do frotz”, tak jakbyś wydawał rozkazy bazie kodu, aby zmienić zachowanie.

Zobaczysz więc wiele komunikatów Git commit napisanych w tym stylu. Jeśli pracujesz w zespole lub w oprogramowaniu open source, pomocne jest, aby wszyscy trzymali się tego stylu, aby zachować spójność. Nawet jeśli pracujesz nad prywatnym projektem i jesteś jedynym, który kiedykolwiek zobaczy twoją historię gitów, pomocne jest zastosowanie trybu rozkazującego, ponieważ ustanawia dobre nawyki, które zostaną docenione podczas pracy z innymi.

Twój projekt powinien prawie zawsze używać czasu przeszłego . W każdym razie projekt powinien zawsze używać tego samego czasu dla spójności i jasności.

Rozumiem niektóre inne argumenty przemawiające za użyciem czasu teraźniejszego, ale zwykle nie mają zastosowania. Poniższe punkty wypunktowane są częstymi argumentami za pisaniem w czasie teraźniejszym i moją odpowiedzią.

• Pisanie w czasie teraźniejszym mówi komuś, co zrobi stosowanie zatwierdzenia , a nie to, co zrobiłeś.

To jest najbardziej poprawny powód, dla którego chciałoby się używać czasu teraźniejszego, ale tylko z właściwym stylem projektu. Ten sposób myślenia traktuje wszystkie zatwierdzenia jako opcjonalne ulepszenia lub funkcje i możesz swobodnie decydować, które zobowiązania zachować, a które odrzucić w swoim repozytorium.

Ten argument działa, jeśli masz do czynienia z naprawdę rozproszonym projektem. Jeśli masz do czynienia z projektem rozproszonym, prawdopodobnie pracujesz nad projektem typu open source. I jest to prawdopodobnie bardzo duży projekt, jeśli jest naprawdę rozproszony. W rzeczywistości jest to prawdopodobnie albo jądro Linuksa, albo Git. Ponieważ Linux jest prawdopodobnie przyczyną rozprzestrzeniania się Gita i jego popularności, łatwo jest zrozumieć, dlaczego ludzie uważają jego styl za autorytet. Tak, styl ma sens w tych dwóch projektach. Lub, ogólnie rzecz biorąc, działa z dużymi, rozproszonymi projektami typu open source .

To powiedziawszy, większość projektów w kontroli źródła nie działa w ten sposób. Jest to zwykle niepoprawne w przypadku większości repozytoriów. Jest to nowoczesny sposób myślenia o zatwierdzeniach: repozytoria Subversion (SVN) i CVS ledwo mogą obsługiwać ten styl sprawdzania repozytorium. Zwykle oddział integracji zajmował się filtrowaniem złych meldowań, ale na ogół nie były one uważane za „opcjonalne” lub „przyjemne w użyciu”.

W większości scenariuszy podczas zatwierdzania do repozytorium źródłowego piszesz zapis w dzienniku, który opisuje zmiany wprowadzone w tej aktualizacji, aby ułatwić innym zrozumienie, dlaczego wprowadzono zmianę. Zasadniczo nie jest to zmiana opcjonalna - inne osoby biorące udział w projekcie są zobowiązane do scalenia lub zmiany bazy. Nie napisać wpis do pamiętnika, takich jak „Drogi pamiętniku, dziś spotkać chłopca, a on mówi cześć do mnie.”, Ale zamiast pisać „Ja spotkałem chłopaka, a on powiedział cześć do mnie.”

Wreszcie, w przypadku takich nierozproszonych projektów, 99,99% czasu osoba czyta komunikat zatwierdzenia służy do czytania historii - historia jest czytana w czasie przeszłym. 0,01% czasu będzie decydowało, czy powinni zastosować to zatwierdzenie, czy zintegrować go ze swoim oddziałem / repozytorium.

• Konsystencja. Tak jest w wielu projektach (w tym w samym git). Robią to również narzędzia git, które generują zatwierdzenia (takie jak git merge lub git revert).

Nie, gwarantuję ci, że większość projektów, które kiedykolwiek zalogowały się w systemie kontroli wersji, miała swoją historię w czasie przeszłym (nie mam referencji, ale prawdopodobnie ma rację, biorąc pod uwagę, że obecny czas jest nowy od Gita). Komunikaty „rewizji” lub komunikaty zatwierdzania w czasie teraźniejszym zaczęły mieć sens tylko w prawdziwie rozproszonych projektach - patrz pierwszy punkt powyżej.

• Ludzie nie tylko czytają historię, aby dowiedzieć się „co się stało z tą bazą kodów”, ale także odpowiedzieć na pytania typu „co się stanie, gdy wybiorę ten plik zatwierdzenia” lub „jakie nowe rzeczy będą się działo z moją bazą kodu z powodu tych zmian Mogę, ale nie chcę scalić w przyszłości ”.

Zobacz pierwszy punkt. 99,99% czasu, kiedy dana osoba będzie czytać komunikat zatwierdzenia, jest przeznaczona do czytania historii - historia jest czytana w czasie przeszłym. 0,01% czasu będzie decydowało, czy powinni zastosować to zatwierdzenie, czy zintegrować go ze swoim oddziałem / repozytorium. 99,99% bije 0,01%.

• Zwykle jest krótszy

Nigdy nie widziałem dobrego argumentu, który mówi, że używaj niewłaściwego czasu / gramatyki, ponieważ jest on krótszy. Prawdopodobnie zaoszczędzisz średnio tylko 3 znaki dla standardowej wiadomości zawierającej 50 znaków. To powiedziawszy, czas teraźniejszy będzie średnio o kilka znaków krótszy.

• Możesz nazwać zatwierdzenia bardziej spójnie z tytułami biletów w swoim narzędziu do śledzenia problemów / funkcji (które nie używają czasu przeszłego, chociaż czasem przyszłego)

Bilety są zapisywane jako coś, co się obecnie dzieje (np. Aplikacja wyświetla nieprawidłowe zachowanie po kliknięciu tego przycisku), lub coś, co należy zrobić w przyszłości (np. Tekst będzie wymagał przeglądu przez redaktora).

Historia (tj. Komunikaty zatwierdzeń) jest zapisywana jako coś, co zostało zrobione w przeszłości (np. Problem został naprawiony).

Pełniejszy opis napisałem na 365git .

Używanie czasu rozkazującego, czasu teraźniejszego wymaga takiego przyzwyczajenia się. Kiedy zacząłem o tym wspominać, spotkałem się z oporem. Zwykle w stylu „Komunikat zatwierdzenia rejestruje to, co zrobiłem”. Ale Git to rozproszony system kontroli wersji, w którym potencjalnie jest wiele miejsc, z których można uzyskać zmiany. Zamiast pisać wiadomości, które mówią, co zrobiłeś; rozważ te komunikaty jako instrukcje dotyczące tego, co zrobi stosowanie zatwierdzenia. Zamiast zatwierdzenia z tytułem:

Renamed the iVars and removed the common prefix.

Miej taki:

Rename the iVars to remove the common prefix

Co mówi komuś, co zrobi stosowanie zatwierdzenia, a nie to, co zrobiłeś. Ponadto, jeśli spojrzysz na historię swojego repozytorium, zobaczysz, że wiadomości generowane przez Git są również zapisywane w tym czasie - „Scal” nie „Scalono”, „Rebase” nie „Rebase”, więc pisanie w tym samym czasie utrzymuje spójność. Na początku wydaje się to dziwne, ale ma sens (referencje dostępne po złożeniu wniosku) i ostatecznie staje się naturalne.

Powiedziawszy to wszystko - to twój kod, twoje repozytorium: więc ustal własne wytyczne i trzymaj się ich.

Jeśli jednak zdecydujesz się pójść tą drogą, git rebase -idobrym pomysłem byłoby skorzystanie z opcji ponownego zapisu.

Trzymaj się czasu teraźniejszego, ponieważ

• dobrze jest mieć standard
• pasuje do zgłoszeń w narzędziu do śledzenia błędów, które naturalnie mają postać „zaimplementuj coś”, „napraw coś” lub „przetestuj coś”.

Dla kogo piszesz wiadomość? I czy ten czytelnik zazwyczaj czyta wiadomość przed lub po posiadaniu, zobowiązuje się?

Myślę, że tutaj podano dobre odpowiedzi z obu perspektyw, być może nie udałoby mi się zasugerować, że istnieje najlepsza odpowiedź dla każdego projektu. Głosowanie podzielone może tyle samo sugerować.

tj. podsumowując:

• Czy wiadomość jest przeważnie dla innych ludzi, zwykle czytających w pewnym momencie, zanim przyjęli zmianę: Propozycja tego, co przyniesie zmiana w ich istniejącym kodzie.

• Wiadomość jest głównie dziennikiem / zapisem dla ciebie (lub twojego zespołu), ale zazwyczaj czyta się z perspektywy przyjęcia zmiany i szukania wstecz, aby odkryć, co się stało.

Być może w obu przypadkach motywuje to Twój zespół / projekt.

czy to ma znaczenie? ludzie są na ogół wystarczająco inteligentni, aby poprawnie interpretować wiadomości, jeśli tak nie jest, prawdopodobnie nie powinieneś pozwolić im na dostęp do twojego repozytorium!

To zależy od Ciebie. Wystarczy użyć komunikatu zatwierdzenia, jak chcesz. Ale łatwiej jest, jeśli nie przełączasz się między czasami i językami.

A jeśli rozwijasz się w zespole - należy to omówić i ustawić na stałe.