Jak stworzyć idealny pull request w 5 krokach

Tworzenie pull requestów to ostatni krok do przedstawienia kodu właścicielom repozytorium i innym kontrybutorom. Bardzo ważne jest dostarczenie dobrego pull requesta, ponieważ pomoże to recenzentom lepiej zrozumieć dostarczony kod. Oto pięć kroków, które możesz zastosować, aby Twój kolejny PR był lepszy niż poprzedni.

1. Branch

Branching oznacza, że odchodzisz od głównej linii developmentu i kontynuujesz pracę bez ingerowania w tę główną. W ten sposób gałęzie Git są niewiarygodnie “lekkie”, dzięki czemu operacje branchingu są niemal natychmiastowe, a przełączanie między gałęziami są równie szybkie.

— Git document.

Nowa gałąź powinna zostać utworzona z ostatniej wersji w gałęzi głównej. Oznacza to, że w punkcie rozgałęzienia commit HEAD gałęzi lokalnej musi być taki sam jak commit HEAD gałęzi głównej.

To pomoże uporządkować historię commitów w zbliżającym się pull request’cie. Aby móc to zrobić, jeśli używasz Gita, możesz wykonać następujące kroki:

git fetch --all #1
git checkout upstream/dev #2
git checkout -b Feature/New #3

• pobrać cały najnowszy kod ze zdalnych repozytoriów
• przełączyć się na ostatni kod w gałęzi z repozytorium
• utworzyć nową gałąź o nazwie Feature/New z najnowszego kodu gałęzi, gdzie jest aktywny development

Możesz także użyć SourceTree i zastosować podobne kroki do tych powyżej, aby osiągnąć to samo.

Jeśli chodzi o nazewnictwo gałęzi, najczęściej spotyka się nazwy takiej jak master, release oraz development. Jakich jednak nazw użyć w przypadku, gdy gałąź służy do refactoringu, stworzenia nowej funkcji czy poprawienia błędu?

Proponuję dwa sposoby.

Nazwy oparte na numerze ticketu lub odpowiadającego problemu

Załóżmy, że pracujesz nad ticketem Jira VAJ-96, który polega na naprawieniu błędu na ekranie głównym. Możesz wtedy nazwać nową gałąź w następujący sposób:

VAJ-96/Fix_Bug_In_Home_Screen

W momencie, gdy jeden ticket wymaga ukończenia wielu gałęzi, można również zastosować tę konwencję nazewnictwa, tak jak tutaj:

VAJ-96/Fix_Bug_1_In_Home_Screen
VAJ-96/Fix_Bug_2_In_Home_Screen
VAJ-96/Fix_Bug_3_In_Home_Screen

Nazwy oparte na typach gałęzi

W cyklu developmentu istnieją co najmniej trzy typy gałęzi, w tym feature’y, poprawki i refaktoryzacje, nad którymi będziesz pracować. Na podstawie tego możemy podzielić nasze gałęzie na następujące kategorie:

Feature/Pet_Dating
Feature/Music_For_Pet

#or
Fix/Loading_Issue
Fix/Crash_In_Home_Screen

#or
Refactor/Duplicated_Code
Refactor/Module_A

Jedną z korzyści, którą zauważysz, jeśli używasz terminala, jest użycie funkcji automatycznego uzupełniania. Jeśli używasz SourceTree, wygląda to tak:

Z łatwością możemy skategoryzować gałąź zgodnie z konwencją.

2. Commit

Aby przygotować świetnego pull requesta, musimy mieć świetną listę commitów. Dlatego ważne jest, jak zdefiniujemy świetnego commita.

Treść commita

Commit powinien zawierać tylko to, co naprawdę niezbędne. Łatwiej jest tworzyć commity, robiąc to regularnie. To pomocne w przypadku, gdybyś musiał cofnąć niektóre commity lub przenieść niektóre z nich do innych gałęzi

Nie czekaj z commitem aż wszystko będzie gotowe, ale też nie commituj każdego napisanego wiersza kodu. Bądź porządnym inżynierem i rób to dobrze!

Nazwa commita

Czy kiedykolwiek widziałeś commita w stylu „to jest commit”, „fix to-do” lub „I don’t know what I am doing”? Brzmi zabawnie, ale to naprawdę się zdarza. Szczerze mówiąc, byłoby koszmarem, gdyby ktoś z Twojego zespołu musiał cofnąć się w przyszłości do tego miejsca i przeczytać coś takiego.

Z tego powodu nazwa commita powinna informować o dokonanych zmianach i może wyglądać następująco:

Fix: - Fixed the crash in Home Screen.
Feature: - Implemented GameView in Play Screen.
Merge: - Merged latest develop to the feature branch.
Chore: - Increased the build number to 68 on Production.
Refactor: - Replaced Singleton pattern by Dependencies Injection.

Niech informacja będzie krótka, ale precyzyjna. Pewnego dnia może Ci to naprawdę pomóc!

I ostatnia, ale nie mniej ważna rzecz - pull request nie będzie idealny, jeśli kod w nim nie będzie czysty ani poprawny. Dlatego bardzo ważne jest, aby upewnić się, że napisany kod jest dobrze skonstruowany, optymalnie napisany i do tego zgodny z zasadami obowiązującymi w danej firmie.

Polecam Ci tutaj odegranie roli recenzenta i samodzielne przejrzenie zmian przed utworzeniem pull requesta w kroku 3. Jeśli jest coś, co Twoim zdaniem mogłoby być lepsze, po prostu to popraw!

Dzięki temu będziesz mieć pewność, że dajesz innym do sprawdzenia swój najlepszy możliwy (na ten moment) kod. To zaoszczędzi wszystkim czasu teraz i później.

3. Zaproponuj zmiany

Idealny pull request powinien mieć jasną nazwę, szczegółowy opis i dodatkowe tagi lub etykiety.

Nazwa pull requesta

Nazwa pull requesta powinna informować o zmianach, aby dać ogólne pojęcie o tym, czego dotyczy. Można kierować się tutaj podobnym szablonem, jak w przypadku commitów, o którym pisałem wyżej.

Opis pull requesta

Opis pomaga recenzentom lepiej zrozumieć motywacje stojące za kodem, to, co było celem do osiągnięcia i punkt widzenia kontrybutora. Powinien zatem odpowiedzieć na trzy pytania: dlaczego, co i jak.

• Dlaczego?- Nad którymi ticketami/problemami/propozycjami(?) pracujesz?
• Co?- Co zrobiłeś?
• Jak?- Co recenzenci powinni wiedzieć?

Załączam przykład, abyś mógł skopiować go w swoim repo. Automatycznie wypełni on domyślny opis dla następnych pull requestów.

### Jira ticket: (or Issue number, or Proposal number)
Please pass the requirement information link which are related to this PR here

### What has changed:
1. Please list down what you have done here
2. Please list down what you have done here
3. Please list down what you have done here

### What reviewers should know:
Please highlight what reviewers should know when reviewing this PR
For example, your new proposal algorithm, your new proposal architecture
Or, show the gif to demo of how the screen you implemented works

Tagi i etykiety

Czasami możesz dodać więcej informacji do pull requesta, aby można było je filtrować i szybciej dowiedzieć się, czego dotyczą. To opcjonalny krok.

Przykład jednego z moich idealnych pull requestów

4. Review

Recenzenci mogą, ale nie muszą, przekazać Ci opinie na temat kodu przed zatwierdzeniem. W takim przypadku ważne jest, aby przed wprowadzeniem jakichkolwiek zmian upewnić się, że dobrze rozumiesz ich sugestie. Na tym etapie mogą wystąpić konflikty, ponieważ recenzenci mogą mieć różne podejścia.

Jeśli więc uważasz, że kod jest poprawny lub Twoje rozwiązanie jest lepsze, możesz bronić swojej wersji i spokojnie wyjaśnić to recenzentom. W przeciwnym razie nie wahaj się modyfikować swojego kodu i commitować zmian - to normalna sytuacja.

Z drugiej strony, jeśli to Ty jesteś recenzentem, skup się na kodzie, a nie na osobie. Działaj profesjonalnie, a pomoże to Tobie i innym.

Nie spędzaj zbyt wiele czasu na debatowaniu i nie nadawaj temu osobistego charakteru. Ostatecznie jesteście zespołem!

5. Akceptacja i merge 

Po rozpatrzeniu wszystkich zmian i uzyskaniu akceptów, możesz scalić je z gałęzią docelową. Istnieje wiele strategii łączenia tego w całość.

Najczęściej używam tu jednej z dwóch strategii: utworzenie commita wynikającego z merge'a nad moimi zmianami oraz połączenie wszystkich moich commitów w jeden duży zestaw zmian i połączenie go z gałęzią docelową w tej formie.

Pierwszej używam głównie do robienia dużych funkcji czy bardziej złożonych refactoringów, dzięki czemu zachowuję historię zmian.

Przy drugiej strategii nie dbamy o historię commitów. Powoduje to połączenia wszystkich commitów, a następnie utworzenie nowego, aby historia była przejrzysta. Dlatego to rozwiązanie dobre jest głównie dla małych feature’ów lub gałęzi z szybkimi poprawkami błędów.

Merge gotowy! Od Ciebie i Twojego modelu branchingu zależy teraz, czy chcesz usunąć oryginalną gałąź, czy zachować ją na przyszłość.

Dziękuję za przeczytanie i mam nadzieję, że lektura tego artykułu sprawi Ci taką samą przyjemność, jak mi jego pisanie. 

Oryginał tekstu w języku angielskim przeczytasz tutaj.