8.8 KiB
| draft |
|---|
| false |
Konwencjonalne Commity 1.0.0-beta
Streszczenie
Jako opiekun open-sourcowego kodu, spłaszczaj (squashuj) gałęzie funkcyjne (featurowe) do gałęzi głównej - master
oraz pisz ustandaryzowane opisy dostarczeń (commitów).
Opis dostarczenia powinien wyglądać następująco:
<typ>[opcjonalny zakres]: <opis>
[opcjonalne ciało wiadomości]
[opcjonalna stopka wiadomości]
Wiadomość zawiera następujące strukturalne elementy po to, aby zakomunikować intencje do użytkowników Twojej biblioteki:
- fix: dostarczenie typu
fixnaprawia błąd obecny w Twoim kodzie (powiązane zPATCHw wersjonowaniu semantycznym). - feat: dostarczenie typu
featwprowadza nowe funkcje do Twojej biblioteki (powiązane zMINORw wersjonowaniu semantycznym). - BREAKING CHANGE: dostarczenie, które posiada tekst
BREAKING CHANGE:na początku jego opcjonalnego ciała bądź stopki wprowadza zmianę łamiącą kompatybilność API (powiązane zMAJORw wersjonowaniu semantycznym). Zmiana łamiąca kompatybilność wsteczną może być elementem zmian typu,fix:lubfeat:.
Przy typie dostarczenia może zostać podany zakres w celu dostarczenia dokładniejszej informacji o kontekście dostarczenia. Zawiera się on w nawiasach następujących bezpośrednio po typie, np.feat(parser): dodano możliwość parsowania list.
Wiadomości typu innego niż fix: oraz feat: są dopuszczalne, na przykład konwencja Angulara poleca docs:, style:, refactor:, perf:, test:, chore:,
jednak tagi te nie są respektowane przez specyfikacje konwencjonalnych Commitów.
Wprowadzenie
Podczas rozwoju oprogramowania zauważyłem, że błędy często występują na granicy pomiędzy aplikacjami. Testy jednostkowe doskonale zdają egzamin w przypadkach, o których opiekun biblioteki pomyślał, jednak sposoby, w jakich oprogramowanie zostanie użyte przez społeczność często, choć interesujące mogą być nie do pomyślenia. Tutaj testy jednostkowe niezbyt zdają egzamin.
Każdy, kto kiedykolwiek zaktualizował zależność swojej aplikacji, chociażby o jedną wersję patch, tylko po to, aby zobaczyć, jak jego aplikacja zaczyna rzucać 500 błędami, wie, jak ważną rolę stanowi czytelna historia dostarczeń (oraz dodatkowo dobrze zarządzany DZIENNIK ZMIAN) podczas naprawy.
Specyfikacja Konwencjonalnych Commitów proponuje wprowadzenie ustandaryzowanej, lekkiej konwencji wykorzystującej wiadomości w dostarczeniach. Konwencja ta łączy się z SemVer, nakazując deweloperom opisywanie w wiadomościach podczas dostarczania jakie funkcje wprowadzają, co naprawiają oraz jakie niekompatybilne wstecz zmiany wnoszą.
Wprowadzając tę konwencję, tworzymy powszechny język, który pozwala na dużo łatwiejsze wyłapywanie błędów występujących na granicy projektu z jego zależnościami.
Specyfikacja
Następujące terminy “MUSI” (“MUST”), “NIE MOŻE” (“MUST NOT”), “WYMAGANY” (“REQUIRED”), “MA BYĆ” (“SHALL”), “NIE BĘDZIE” (“SHALL NOT”), “POWINIEN” (“SHOULD”), “NIE POWINIEN” (“SHOULD NOT”), “ZALECANY” (“RECOMMENDED”), “MOŻE” (“MAY”) oraz “OPCJONALNY” (“OPTIONAL”) pojawiające się w tym dokumencie rozumiane są zgodnie z ich opisem na stronie: RFC 2119.
- Dostarczenie MUSI być poprzedzone typem, który składa się z rzeczownika, np.
feat,fix, itp., oraz następującymi bezpośrednio po nim dwukropka oraz spacji. - Typ
featMUSI być użyt, gdy dostarczenie dodaje nową funkcję do Twojej aplikacji bądź bibliteki. - Typ
fixMUSI być użyty, kiedy dostarczenie naprawia błąd w Twojej aplikacji. - Opcjonalny zakres MOŻE być podany po typie. Zakres jest to fraza opisująca obszar kodu zawarta w nawiasach okrągłych, np.,
fix(parser): - Opis MUSI występować zaraz po przedrostku typu/zakresu. Opis jest to krótka notka stanowiąca o treści dostarczenia, np., fix: problem podczas parsowania listy, kiedy string zawierał wiele spacji.
- Dłuższe ciało wiadomośći MOŻĘ być podane po krótkim opisie. Ciało MUSI zaczynać się jedną pustą linię po opisie.
- Stopka MOŻE być podane jedną linię za ciałem wiadomości. Stopka POWINNA zawierać dodatkowe informacje odnośnie zgłoszeń błędów lub propozycji funkcjonalności, które rozwiąznuje, np.
fixes #13, #5. - Zmiany niekompatybilne wstecz MUSZĄ być zaznaczone na samym początku sekcji ciała wiadmości lub stopki. Informacja o niekompatybilności MUSI zawierać tekst
BREAKING CHANGE, wraz z następującymi po nim dwukropkiem oraz spacją. - Po tekście
BREAKING CHANGE:MUSI następować opis mówiący o tym, co zostało zmienione w kodzie w sposób, który niszczy kompatybilność wstecz, np. BREAKING CHANGE: zmienne środowiskowe mają teraz większy priorytet niż pliki konfiuguracyjne. - Typy inne niż
featorazfixMOGĄ być użyte w wiadomościach Twoich dostarczeń.
Dlaczego używać Konwencjonalnych Commitów
- Automatycznie generowany DZIENNIK ZMIAN.
- Automatycznie wykrywana zmiana semantycznej zmiany wersji (określana na podstawie typów dostarczonych zmian)
- Komunikowanie zmian członkom zespołu, publice, oraz innym zainteresowanym.
- Wyzywalanie procesów budowania oraz publikacji.
- Łatwiejsze włączenie się w rozwój kodu przez ludzi z zewnątrz poprzez pozwolenie im na przeglądanie bardziej zorganizowanej historii dostarczeń.
FAQ
Jak powinienem radzić sobie z wiadomościami dostarczeń w fazie początkowej rozwoju kodu?
Polecamy, żebyś postępował tak, jakby Twój produkt już został wydany. Zazwyczaj ktoś, nawet jeśli jest to Twój kolega z zespołu, już używa Twojego oprogramowania. Będzie chciał wiedzieć, co zostało naprawione, co nie działa itp.
Co powinienem zrobić, jeśli dostarczenie pasuje do więcej niż jednego typu?
Wróć się i stwórz więcej dostarczeń, jeśli to tylko możliwe. Częściową korzyścią z Konwencjonalnych Commitów jest zdolność do tworzenia kodu w bardziej zorganizowany sposób.
Czy takie podejście nie zniechęca do szybkiego rozwoju oraz szybkich iteracji?
Zniechęca do szybkiego poruszania się do przodu w niezorganizowany sposób. Pozwala Ci na szybkie posuwanie się do przodu w wielu projektach oraz różnorodnych deweloperów.
Czy Konwencjonalne Commity mogą prowadzić do zmniejszenia ilości typów dostarczanych przez deweloperów, ponieważ będą myśleć w przestrzeni wymienionych typów?
Konwencjonalne Commity zachęcają do tworzenia większej ilości dostarczeń danego typu, np. napraw. Z innego punktu widzenia, elastyczność Konwencjonalnych Commitów pozwala Twojemu zespołowi stworzyć własne typy oraz zmieniać je z biegiem czasu.
Jak jest to powiązane z SemVer?
Wiadomości typu fix powinny być traktowane tak jak PATCH. Wiadomości typu feat tak jak MINOR, natomiast dostarczenia zawierające BREAKING CHANGE, bez względu na typ, powinny być traktowane jak MAJOR.
Jak powinienem wersjonować moje rozszerzenia zgodnie ze specyfikacją Konwencjonalnych Commitów, np. @jameswomack/conventional-commit-spec?
Zalecamy używanie SemVer do wydawania własnych rozszerzeń do tej specyfikacji (oraz zachęcamy do tworzenia tych rozszerzeń!).
Co powinienem zrobić, jeśli przypadkowo użyje błędnego typu dostarczenia?
Jeśli użyłeś typu, który znajduje się w specyfikacji, ale nie jest poprawny, np. fix zamiast feat
Przed dostarczeniem i wydaniem pomyłki, polecamy użyć git rebase -i w celu zmienienia historii dostarczeń. Zmiana po dostarczeniu zależy od narzędzi oraz procesów, których używasz.
Jeśli użyłeś typu, który nie znajduje się w specyfikacji, np. feet zamiast feat
W najgorszym przypadku - to nie koniec świata, jeśli dostarczenie niespełniające specyfikacji Konwencjonalnych Commitów zostanie wprowadzone. Po prostu znaczy to, że będzie pominięty przez narzędzia bazujące na specyfikacji.
Czy wszyscy moi kontrybutorzy muszą używać specyfikacji Konwencjonalnych Commitów?
Nie! Jeśli używasz trybu bazującego na spłaszczaniu historii dostarczeń, wtedy główni opiekunowie projektu mogą posprzątać wiadomości podczas dostarczania. Takie podejście nie narzuca żadnego obowiązku na osoby dostarczające od czasu do czasu. Powszechnym podejściem jest używanie automatycznego spłaszczania historii dostarczeń z pull requestóœ oraz wyświetlenie formularza osobie dostarczającej w celu wypełnienia wiadomości poprawną treścią.