Git pull request, GitHub pull request

Git jako najpopularniejszy rozproszony system kontroli wersji – może się pochwalić rozbudowanym zbiorem funkcjonalności oraz różnego rodzaju integracji – co pozwala wykorzystać go swobodnie w wielu codziennych zadaniach.
W ramach tego materiału dowiesz się jak stworzyć prośbę o zatwierdzenie zmian – czyli z ang. pull request.

Git pull request – wprowadzenie

Z tego materiału dowiesz się:

• Czym jest pull request?
• Jak przygotować zmiany przed pull request’em?
• Jak tworzyć pull request w GitHub’ie?
• Jakie opcje daje GitHub podczas tworzenia pull request’a?

Git install – Instalacja Git

Jeżeli nie masz jeszcze Gita zainstalowanego lokalnie – szybko możesz to nadrobić.
W poniższym materiale znajdziesz instrukcję, jak można to zrobić.

➡ ZOBACZ 👉: Install Git – Instalacja Git, Windows, Ubuntu – Bash, GUI

Git

W ramach tego materiału zajmiemy się przede wszystkim tworzeniem pull request’a – natomiast kompletny tutorial Git i Git pull znajdziesz poniżej.

➡ ZOBACZ:

👉 Git tutorial | stash, rebase, commit, merge, checkout, push i clone

👉 Git fetch vs. pull | Git fetch, git pull

Pull request – prośba o zaakceptowanie zmian

Jednym z zadań programistów jest kontrola jakości kodu, który będzie wdrożony do aplikacji. Pilnujemy nie tylko jakości własnego kodu – ale również innych członków zespołu.

Ważne jest, aby pamiętać, że praca innych również może mieć wpływ na efektywność naszej pracy w przyszłości. Wyobraź sobie, że ktoś napisał fatalnie jakiś fragment kodu, który został zmergowany z głównym branch’em bez wcześniejszego code review.
Okazuje się, że po jakimś czasie to Ty musisz nanieść pewne poprawki na ten kod – ale najpierw dość sporo czasu zajmuje Ci zrozumienie tego kodu – ponieważ, pomimo że nasz kod teoretycznie działa, to panuje w nim totalny chaos! 😱
O ile łatwiej byłoby pracować nad kodem, który jeszcze przed przyłączeniem został porządnie sprawdzony (czyli nasze brakujące code review!)?

Jednym z popularniejszych narzędzi, które możesz w tym celu wykorzystać jest pull request.

Pull request

Pull request jest formą poinformowania osób zaangażowanych w projekt o nowych przygotowanych przez Ciebie zmianach oraz prośbą o zaakceptowanie tych zmian.
Podczas tworzenia pull request’a generuje się widok w wybranym narzędziu (np. GitHub, czy Bitbucket), który pokazuje zmiany w kodzie, które chcemy wprowadzić. Zmiany można omówić przez m.in. dodanie komentarzy i ostatecznie zaakceptować, wstrzymać lub całkowicie odrzucić.

Stworzyć pull request to trochę tak, jakby powiedzieć członkom zespołu – Hej, ja już skończyłem pracę nad tym zadaniem i tak to wygląda – zweryfikujcie, proszę, bo chcę to wdrożyć do naszej aplikacji.

Taki przegląd kodu – czyli z ang. code review – jest jedną z dobrych praktyk programistycznych, która pozwala utrzymać porządek w kodzie naszych aplikacji.

➡ ZOBACZ 👉: Code Review| Nie wiesz jak pisać lepszy kod? Skup się na code review (przegląd kodu)!

Create pull request – GitHub – tworzenie prośby o zaakceptowanie zmian

Istnieją różne narzędzia pracujące z systemem kontroli wersji, jakim jest Git. Jednym z najpopularniejszym jest GitHub.

GitHub zapewnia nam czytelny i dosyć intuicyjny interfejs, który pozwala nam w łatwy sposób stworzyć pull request i przeprowadzić analizę kodu (ang. code review).

Co to oznacza jednak w praktyce? Spójrzmy 😊

Proces, jakim jest stworzenie pull reqeust’a dzieli się na dwie główne części:

• Tworzenie zmian lokalnie i przesyłanie ich do zdalnego repozytorium.
• Tworzenie pull request’a.

Tworzenie zmian lokalnie – praca na lokalnym repozytorium

1. Stworzenie nowej gałęzi z głównego branch’a – git checkout -b

Moim głównym branch’em jest w tym przypadku master. Jeżeli obecnie znajdujesz się na innym branch’u niż główny branch, z którego chcesz się odbić, wystarczy, że użyjesz git checkout master. Nie jest konieczne przełączanie się na branch’a, na podstawie którego chcesz stworzyć nową gałąź. Jednak dobrze jest najpierw doprowadzić gałąź źródłową do najbardziej aktualnego stanu. To właśnie zrobiłam na poniższym przykładzie. Zastosowałam git fetch, który odświeżył lokalne repozytorium o najnowsze dane oraz git pull, który oprócz odświeżenia przyłącza te dane do naszej lokalnej wersji. W tym przypadku okazało się, że mój master był na bieżąco ze zdalnym repozytorium.

W momencie, w którym wiedziałam, że master ma najnowsze dane, stworzyłam na jego podstawie nowego branch’a animal za pomocą git checkout -b animal. Polecenie to stworzyło nowego branch’a i od razu mnie na niego przełączyło. Na potrzeby zadania gałąź nazwałam animal. W projektach jednak panuję przeważnie określona już z góry konwencja nazewnictwa nowych branch’y np. feature/<nazwa> lub też bugFix/<nazwa>.

➡ ZOBACZ:

👉 Git branch | git branch create, rename, delete, checkout, merge

👉 Git checkout, git checkout remote branch, git switch

2. Stwórz zmiany i zapisz je w lokalnym repozytorium – git commit

Na moim nowo powstałym branch’u animal stworzyłam klasę Animal. Kolejnymi krokami było:

• Dodanie nowo stworzoną klasę do przechowalni (ang. stage) za pomocą polecenia git add.
  (kropka oznacza dodanie wszystkich utworzonych plików z głównego katalogu – można też wykorzystać flagę -A, żeby dodać wszystkie pliki).
• Zapisanie tych zmian w lokalnym repozytorium używając git commit.

Treść commit’a powinna zawierać tylko to, co naprawdę istotne i niezbędne. Pamiętaj, że możesz tworzyć więcej commit’ów niż tylko jeden. Większe funkcjonalności można i warto podzielić na mniejsze części. Jeżeli każdą część zapiszesz w osobnym commicie będziesz mógł łatwo prześledzić historię zmian i w razie potrzeby cofnąć pojedynczą małą zmianę. Zdecydowanie łatwiejsze będzie przeanalizowanie tego, co zadziało się w kodzie, jeżeli stworzysz kilka commit’ów np.:

• „Implemented saving user data”,
• „Implemented updating user data”,
• „Implemented deleting user data”

niż samo: „Implemented user functionalities”.

Oczywiście jak zawsze trzeba uważać, by nie popaść w przesadę i nie przesadzić z rozdrobnieniem zmian.

Zwróć też uwagę na to, że nazwy commit’ów zapisuję w języku angielskim. Duża ilość projektów jest tworzona w tym języku (zmienne, nazwy metod itd.), dlatego warto już nawet tylko ćwicząc tworzyć nazwy commit’ów po angielsku.

Zachowaj czytelną i zrozumiałą dla wszystkich konwencję nazewnictwa. Nazwa commit’a powinna być konkretna oraz jednoznaczna, która mówi, co robisz. Kontekst powinien być od ogółu do szczegółu.

Przykładowo:

• Fix: – Fixed the crash in Home Screen (pl. Naprawiono awarię na ekranie głównym).
• Feature: – Implemented GameView in Play Screen (pl. Zaimplementowano widok gry na ekranie gry).
• Merge: – Merged latest develop to the feature branch (pl. Przyłączenie najnowszej wersji gałęzi develop do gałęzi feature).
• Chore: – Increased the build number to 68 on Production (pl. Zwiększenie numeru build’a do 68 na produkcji).
• Refactor: – Replaced Singleton pattern by Dependencies Injection (pl. Zastąpienie wzorca Singleton wstrzykiwaniem zależności).

➡ ZOBACZ:

👉 Git commit – git commit amend

3. Wypchnij lokalne zmiany do zdalnego repozytorium – git push

Nasze lokalne zmiany są już zapisane i nadszedł czas, aby poinformować zdalne repozytorium o ich istnieniu. W tym celu wykonamy polecenie git push.

Na poniższym przykładzie użyłam git push -u origin animal i od tego momentu moje zdalne repozytorium już wie o istnieniu brancha animal.

➡ ZOBACZ:

👉 Git push – git integracja ze zdalnym repozytorium, git push, ssh, remote

Przygotowanie pull request – GitHub

Czas przenieść się do GitHub’a. Jak widać na poniższym przykładzie, GitHub już wie, o naszym nowym branch’u i zmianach, które na nim powstały.

Pojawiło się powiadomienie o zmianach wypchniętych na branch’u animal i możliwość stworzenia pull request’a – przycisk: Compare & pull request.

Sprawdźmy, co kryję się pod tym przyciskiem.

Na powyższej grafice widać kilka punktów, którym warto się przyjrzeć:

1. Informacja o przyłączaniu gałęzi – opisy: base i compare oraz ←, w czytelny sposób pokazują, który branch będzie przyłączany do którego. W tym przypadku gałęzią podstawową (ang. base) jest branch master, gałęzią porównywaną (ang. compare) i przyłączana do mastera jest gałąź animal, na co wskazuje kierunek strzałki.
Warto też zauważyć, że po prawej stronie pojawiła się informacja Able to merge. W praktyce oznacza to, że nie pojawiły się w tym przypadku żadne konflikty (ang. merge conflicts).

2. Nazwa pull request’a – GitHub automatycznie ustawia nazwę pull request’a, która jest nazwą ostatniego commit’a. Tak samo, jak w przypadku nazywania commit’a tak i w tym przypadku nazwa powinna być czytelna, zrozumiała i wskazywać dokładnie na to, co zmieniło się w kodzie w danym pull requeście.

3. Komentarz – opcjonalnie możemy zostawić komentarz, który pomoże recenzentom lepiej zrozumieć Twoją motywację, co było celem wprowadzonych zmian i punkt widzenia dodającego kod.

4. Stworzenie pull request’a – jeżeli wypełniliśmy wszystkie pola, które musiały być wypełnione i te, o które chcieliśmy poszerzyć nasz pull request możemy go utworzyć.

Po utworzeniu pull request pojawia się nam kilka informacji i dodatkowych opcji.

1. Zakładki – szczególnie istotne dla nas:

• Conversation – zakładka, którą widać powyżej. To tutaj możesz zatwierdzić lub odrzucić pull request’a.
• Commits – lista commit’ów znajdujących się w tym pull requeście.
• File changed – pliki, w których dokonaliśmy zmian. W tej zakładce można sprawdzić różnice pomiędzy tym, jak wyglądał plik przed i po wprowadzeniu Twoich zmian.

2. Informacja o konfliktach – GitHub automatycznie sprawdza, czy występują potencjalne konflikty, które pojawią się podczas przyłączania naszej gałęzi. W tym przypadku takie konflikty nie występują.

3. Przyłączenie zmian – przycisk, którym zatwierdzamy i przyłączamy zmiany z pull request’a do branch’a docelowego. Tutaj jest to branch master.

Inne dwie możliwości, które możesz tutaj zauważyć to dodanie komentarza oraz zamknięcie pull request’a (ang. Close pull request).

Zamknięcie pull request’a nie jest jednak ostatecznym krokiem, którego nie można cofnąć. Istnieje możliwość ponownego otworzenia tego samego pull request’a (ang. Reopen pull request).

Code review – przegląd kodu – File changed

Tworzenie pull request’a ma na celu sprawdzenie zmian, zanim trafią one na głównego branch’a. Jest to bardzo ważny punkt, ponieważ to od niego zależy czy przyłączymy dobrze napisany, działający kod, który będzie czytelny i łatwy w poruszaniu się dla innych programistów.

1. File changed – aby sprawdzić zmiany, wprowadzone w danym pull requescie musisz wejść w zakładkę File changed.
2. Komentarze – zdecydowanie praktyczną funkcją, którą daje nam GitHub, jest możliwość dodawania komentarzy do każdej linii kodu. Ułatwia to zarówno pracę osobie, która przeprowadza review, jak i osobie, której kod jest sprawdzany.

Poniżej widać opcje filtrowania, z których możesz korzystać, aby ułatwić i tak naprawdę przyspieszyć pracę nad review.

• Change from – możesz filtrować po wszystkich commit’ach, ale również wybrać konkretny commit do sprawdzenia. Ciekawą opcją jest możliwość zobaczenia tylko tych zmian, które zostały wprowadzone od ostatniego review.
• File filter – możliwość filtrowania po konkretnych plikach np.: .java, .xml.
• Conversations – filtrowanie po konwersacjach przeprowadzonych w trakcie review.
• Jump to – przeskoczenie do konkretnego pliku np. Animal.java.

Review changes

Podczas sprawdzania kodu, może być tak naprawdę kilka scenariuszy, które mogą się wydarzyć.
Najbardziej optymistycznym jest oczywiście zatwierdzenie zmian (ang. Approve).
Może się jednak zdarzyć, że wg. osoby sprawdzającej, kod wymaga pewnych poprawek i wtedy reviewer wybiera opcje Request changes. Zmiany, które mają być dokonane, powinny być określone w komentarzach, przy poszczególnych liniach kodu. Ułatwi to zdecydowanie prace osobie odpowiedzialnej za dany kod.

Code review – czyli przegląd kodu

W ramach tego materiału zajmujemy się przede wszystkim tworzeniem pull request’a – natomiast kompletny tutorial Code Review znajdziesz poniżej.

➡ ZOBACZ 👉: Code Review| Nie wiesz jak pisać lepszy kod? Skup się na code review (przegląd kodu)!

Akceptacja i merge

Ostatnim i zdecydowanie nie mniej ważnym krokiem jest przyłączenie zmian do docelowej gałęzi.
Po rozpatrzeniu sugestii, poprawkach i akceptacji zmian, można już spokojnie scalić naszą zmianę z gałęzią docelową.

Czy to zagwarantuje, że wszystko będzie ok? No nie 🙂

Jesteśmy tylko ludźmi dlatego może zdarzyć się, że czegoś nie wyłapaliśmy. Jednak dzięki temu, że zostało przeprowadzone porządne code review – dajemy sobie pewien kredyt zaufania, że zrobione zostało wszystko to, co powinno być, aby przyłączany kod był jak najlepszy.

Aby scalić zmiany, musisz wrócić do zakładki Conversation.

Istnieje kilka strategii łączenia zmian:

• Utworzenie merge commit’a wynikającego z merga i dodanie wszystkich commit’ów ze scalanego branch’a do historii zmian branch’a docelowego.
• Zastosowanie git squash, który połączy wszystkie commit’y ze scalanego branch’a w jeden wspólny commit.
• Zastosowanie rebase, który nie utworzy merge commit’a, a commit’y ze scalanego branch’a będą dodawane pojedynczo do gałęzi podstawowej. W ten sposób zostanie zachowana liniowa historia projektu.

To jaką strategię wybierzesz, zależy przeważnie od zasad, jakie panują w projekcie lub w przypadku mniejszych prywatnych projektów od osobistych preferencji.

Kiedy zmiany zostały przyłączone, możemy, a nawet powinniśmy zrobić porządek po sobie. Jeżeli wiemy, że gałąź, którą właśnie przyłączyliśmy, nie będzie nam już potrzebna, usuńmy ją. Nie zaśmiecajmy zdalnego repozytorium (ale również lokalnego) już niepotrzebnymi branch’ami.

Pull request – podsumowanie

W ramach tego materiału przećwiczyliśmy tworzenie prośby o zatwierdzenie zmian (ang. pull request). Zapoznaliśmy się z wieloma niezwykle przydatnymi opcjami m.in. jak przy pomocy GitHub efektywnie stworzyć i sprawdzić pull request’a.

Jeżeli chcesz kontynuować swoją przygodę z gitem – to zapraszam do dodatkowych materiałów:

➡ ZOBACZ 👉: Git tutorial | stash, rebase, commit, merge, checkout, push i clone