Na pewnym etapie nauki korzystanie z systemu kontroli wersji staje się koniecznością. Jeśli więc zacząłeś zapoznawać się z Gitem, ale brakuje ci doświadczenia lub znajmości dobrych praktyk, to miejsce właśnie dla Ciebie. Istnieje wiele serwisów hostujących repozytoria Git, które ułatwiają przechowywanie kodu, śledzenie zmian i współpracę zespołową przy tworzeniu oprogramowania, jak Github, Microsoft Azure, GitLab, BitBucket. Niezależnie od tego, z którego z nich korzystasz, porady związane z tworzeniem pull requestów będą w większości uniwersalne, choć ten artykuł skupia się wokół uniwersum Githuba.

Pull request (PR) jest mechanizmem, który służy do proponowania zmian w kodzie. Najprościej mówiąc:

1. Tworzysz gałąź (branch), na której dokonasz zmian, np. poprawki błędu czy modyfikacji funkcjonalności

2. Wprowadzasz zmiany w kodzie i zapisujesz je w commitach

3. Wysyłasz (pushujesz) gałąź do zdalnego repozytorium.

4. Otwierasz pull requesta czyli prosisz o wciągnięcie (merge) Twoich zmian do głównej gałęzi projektu (np. develop).

5. Inni członkowie zespołu mogą wtedy przejrzeć zmiany (code review), dodać komentarze, zasugerować poprawki.

6. Jeśli wszystko jest OK, ktoś (często maintainer projektu) akceptuje i łączy pull requesta z docelową gałęzią.

Pull requesty przeszły sporo zmian od swoich początków. W 2008 roku, kiedy powstał GitHub, PR był właściwie zwykłym powiadomieniem wysyłanym do opiekuna repozytorium. Taki mały sygnał w stylu: Hej, mam zmiany, które możesz chcieć wciągnąć do projektu. W 2010 roku GitHub przekształcił PR-y z tymczasowych powiadomień w trwałe, publiczne zapisy dyskusji. Każdy PR stał się dedykowaną przestrzenią do rozmowy. W 2011 dodano możliwość komentowania bezpośrednio w widoku różnic (diff), co było początkiem PR-a, jaki znamy dzisiaj. To umożliwiło kontekstowe dyskusje na poziomie pojedynczych linii kodu.

PR przygotowujesz biorąc pod uwagę zarówno jakość kodu, jak i komfort kolegów, którzy przecież wkrótce dostaną go do review. Tak jak klasa lub funkcja powinna mieć jeden, dobrze zdefiniowany cel, tak PR powinien obejmować jedną, spójną, logiczną część Twojej pracy. Taki PR jest znacznie łatwiejszy do zrozumienia, zrecenzowania, przetestowania, a w razie potrzeby, bezpiecznego wycofania. Pull request to historia opowiadana za pomocą commitów. Aby ta historia była czytelna i logiczna, najlepiej gdyby składała się z commitów atomowych, a więc wprowadzających tylko jedną logiczną zmianę, np. naprawa jednego błędu czy dodanie jednej funkcji. Oznacza to, że po każdym commicie wszystkie testy powinny przechodzić pomyślnie. Pull request złożony z serii takich commitów tworzy logiczną, krok po kroku opowieść o tym, jak powstawało rozwiązanie, zamiast być jednym, ciężkim blokiem zmian.

Aby wprowadzić porządek i spójność w historii, zaleca się stosowanie specyfikacji Conventional Commits. To lekka konwencja, która narzuca prostą strukturę komunikatów (messages). A w commicie wygląda następująco:

git commit -m "<typ>(<zakres>): <temat>"

Zakres jest opcjonalny i określa część codebase'u, której dotyczy zmiana (np. api, auth). Natomiast temat to krótki opis, co zostało zmodyfikowane.

Możliwe typy:

Przykłady:

Języka polskiego używam w kodzie tylko w celach poglądowych. Sstandardem w branży jest angielski (dzięki temu łatwo można m.in. dodać do zespołu ludzi z innych krajów).

Jeśli stosujesz tę konwencję, jasno komunikujesz intencje każdej zmiany. Umożliwia to także automatyzację procesów, takich jak generowanie changelogów, określanie nowej wersji oprogramowania czy walidacja komunikatów w potoku CI/CD.

Najlepszą praktyką, jaką możesz zastosować jako autor kodu, jest wprowadzanie małych, przyrostowych zmian. W branży krąży pewna zabawna myśl, które świetnie to obrazuje:

To niestety prawda poparta licznymi badaniami. Skuteczność recenzującego (przy code review) drastycznie spada podczas analizy dużych zmian. I nie jest to nawet liniowy spadek. Po przekroczeniu pewnego progu poznawczego, code review przestaje być efektywne i staje się tylko formalnością.

Idealny rozmiar PR to przedział 25-100 linii kodu, z optymalnym punktem w okolicach 50 linii. Pull Requesty poniżej 200 linii są recenzowane i włączane do głównej gałęzi kodu znacznie szybciej.

Zmiany o wielkości 50 linii mają o 15% mniejsze prawdopodobieństwo wycofania (revert) niż zmiany o wielkości 250 linii. Gęstość wykrywanych błędów gwałtownie spada, gdy tempo code review przekracza 500 linii kodu na godzinę, co jest nieuniknione przy dużych PR.

• Duże funkcjonalności powinny być dzielone na mniejsze, logiczne części. Wdrożenie ścisłego limitu rozmiaru PR jest jedną z najbardziej wpływowych zmian, jakie zespół może wprowadzić. Zmusza to deweloperów do myślenia w mniejszych, bardziej spójnych jednostkach, co wpływa też na jakość kodu.

• Należy grupować zmiany - oddzielać refaktoryzację (przebudowę kodu), poprawki błędów i nowe funkcje do osobnych PR.

• Warto stosować "Stacked PRs/Diffs". Jest to zaawansowana technika, w której duża zmiana jest dzielona na serię zależnych od siebie, mniejszych PR, przeznaczonych do recenzowania sekwencyjnie. Każdy PR w stacku bazuje na poprzednim, co pozwala na stopniowe wprowadzanie i weryfikację złożonej funkcjonalności. Prawdopodobnie na razie nie będzie interesować Cię to zagadnienie, ale warto wiedzieć, że taki mechanizm istnieje.

Pull Request to propozycja, która wymaga opowiedzenia. Powinieneś w jasny i kompletny sposób opisać wprowadzane zmiany, by recenzujący mogli zrozumieć kontekst, cel i konsekwencje wprowadzanych modyfikacji. PR jest formą komunikacji technicznej, która przygotowana słabo, tworzy dług komunikacyjny, przenosząc ciężar zrozumienia z autora na cały zespół.

Słynne powiedzenie zacytowane na początku tego artykułu, doskonale oddaje istotę problemu z poznawczym przetworzeniem dużej ilości kodu. I wynika to z ograniczeń ludzkiej zdolności do procesowania informacji. Duże zmiany przytłaczają, co prowadzi do powierzchownych recenzji i przeoczenia subtelnych błędów.

Badania potwierdzają tę intuicję. Analiza przeprowadzona w Cisco Systems wykazała, że zdolność dewelopera do wykrywania defektów drastycznie spada po przekroczeniu 200-400 linii zmienionego kodu (LOC). W wielu firmach dąży się do tego, by PR-y nie przekraczały 50 LOC. Co więcej, zespoły utrzymujące średni rozmiar PR na takim właśnie poziomie dostarczają o 40% więcej kodu niż te, których PR-y przekraczają 200 linii.

Najbardziej bezpośrednią i odczuwalną korzyścią małych PR-ów jest skrócenie czasu potrzebnego na uzyskanie informacji zwrotnej. Niska złożoność zadania sprawia, że review staje się zadaniem, które można wykonać w ciągu kilku minut, a nie godzin, co zachęca do szybkiego działania.

Wiodące firmy technologiczne traktują szybkość tego procesu jako kluczowy wskaźnik. Wewnętrzne wytyczne Google'a zalecają, by czas odpowiedzi na prośbę o review nie przekraczał 24 godzin roboczych. Taki standard jest możliwy do utrzymania tylko wtedy, gdy pull requesty są małe i łatwe do przyswojenia.

Zmiany o niewielkim zakresie są łatwiejsze do zrozumienia, kompleksowego przetestowania i dokładnego zrecenzowania. Prowadzi to bezpośrednio do mniejszej liczby błędów lądujących w głównej gałęzi kodu. Każdy PR jest dzięki temu jak chirurgiczna operacja, a nie ryzykowny przeszczep organów ;)

Gdy wdrożona zmiana powoduje krytyczny błąd na produkcji, czas reakcji jest kluczowy. Mały, skoncentrowany PR można wycofać za pomocą jednego polecenia git revert, czysto usuwając problematyczny kod. Próba wycofania PR, który miesza ze sobą nowe funkcje, poprawki błędów i refaktoryzację, jest koszmarem, który może wprowadzić jeszcze więcej problemów.

Im dłużej feature branch żyje w izolacji, tym bardziej oddala się od głównej gałęzi. To geometrycznie zwiększa prawdopodobieństwo i złożoność konfliktów podczas mergowania. Małe, często scalane PR-y minimalizują to ryzyko, sprawiając, że jest to proste, rutynowe zadanie.

Opis PR powinien odpowiadać na trzy pytania:

1. Co się zmieniło? (krótkie podsumowanie implementacji).

2. Dlaczego ta zmiana była potrzebna? (wyjaśnienie logiki biznesowej czy natury błędu).

3. Jak można to przetestować/zweryfikować? (kroki do manualnej weryfikacji, zrzuty ekranu, nagrania wideo).

W przypadku wszelkich zmian w interfejsie użytkownika, zrzuty ekranu lub GIF-y typu przed i po będą pomocne. Dostarczą kontekstu, którego sam kod nie jest w stanie przekazać.

Dodawaj też adnotacje do własnego kodu przed wysłaniem go do review. Komentarze mogą wskazywać na złożone fragmenty, wyjaśniać podjęte decyzje projektowe lub zadawać pytania recenzentom. Taka praktyka nie tylko przyspiesza pracę innym, ale może pomóc także Tobie samodzielnie znaleźć błędy.

Trzymanie się jednego szablonu PRów w projekcie również ułatwia ich czytanie, bo wtedy każdy wygląda podobnie. Dzięki temu nie musimy za każdym razem uczyć się od nowa, co i jak zostało opisane.

Kod, który napiszesz zostanie udostępniony innym członkom zespołu do weryfikacji, czyli code review. Zanim się to odbędzie powinieneś poczynić kilka przygotowawczych kroków.

1. Najpierw auto-recenzja: pierwszym recenzentem Twojego kodu jesteś Ty sam. Dokładne przejrzenie własnego diffa jest niezbędne do wyłapania literówek, zakomentowanego kodu, pozostawionych instrukcji console.log i innych oczywistych błędów.

2. Lintery i formatery: cały kod musi być zgodny ze standardami formatowania, jaki przyjęliście dla tego projektu. Proces ten powinien być w pełni zautomatyzowany, by recenzujący nie marnowali czasu na uwagi dotyczące formatowania. Więc automatyczne narzędzia: Prettier, ESLint, Stylelint uruchom przed pull requestem.

3. Uruchomienie wszystkich testów: PR musi pomyślnie przejść wszystkie powiązane testy jednostkowe, integracyjne i systemowe przed przesłaniem do review.

4. Czystość i minimalizm: PR powinien zawierać tylko niezbędne modyfikacje i tylko te dotyczące wykonywanego zadania. Należy usunąć zakomentowany kod, niepotrzebne zmiany w białych znakach i pliki, które nie są związane z głównym celem.

Tworzenie dobrych pull requestów pokazuje, że zależy ci nie tylko na tym, by kod działał, ale jest też objawem szacunku dla innych członków zespołu. Kiedy robisz PR starannie, z jasnym opisem i w logicznych kawałkach, oszczędzasz czas kolegom, którzy będą go przeglądać. Zespół rozwija kulturę pracy, w której każdy czuje odpowiedzialność za jakość i komfort wspólnych działań.