Magia Pull Requestów

1. Od scalenia do propozycji: po co są Pull Requesty?

Na poprzedniej lekcji nauczyliśmy się scalać (merge) gałęzie na swoim lokalnym komputerze. To świetnie działa, gdy pracujesz sam. Ale co, jeśli nad projektem pracuje cały zespół? Jeśli każdy będzie scalał swoje zmiany bezpośrednio do głównej gałęzi main, bardzo szybko zacznie się chaos: ktoś może przypadkowo dodać kod z błędami, zepsuć build albo usunąć ważną część pracy kolegi.

Aby tego uniknąć, w pracy zespołowej przyjęto inne podejście. Zamiast od razu scalać zmiany, tworzysz propozycję scalenia. Taka propozycja nazywa się Pull Request (w skrócie PR) lub — na niektórych platformach — Merge Request.

Pull Request — to oficjalna prośba: „Proszę, pobierzcie (pull) moje zmiany z mojej gałęzi i dodajcie (merge) je do głównej gałęzi”. Ale to nie tylko prośba, lecz cała przestrzeń do dyskusji, weryfikacji i ulepszania kodu zanim trafi do main.

2. Standardowy workflow z Pull Requestem

Przejdźmy krok po kroku przez typowy workflow przy tworzeniu nowej funkcjonalności.

Zanim utworzysz gałąź dla nowego zadania, upewnij się, że wypchnąłeś wszystkie ukończone commity (push) i zaktualizowałeś (Update Project) główną gałąź main.

W przeciwnym razie wszystkie twoje „zapomniane” lokalne commity z main przypadkiem trafią do nowego Pull Requesta, tworząc zamieszanie dla twoich kolegów.

Krok 1. Utwórz gałąź dla nowego zadania.

Jak wcześniej, każdą nową pracę zaczynasz od utworzenia osobnej gałęzi. Załóżmy, że chcemy dodać do naszego projektu plik z zasadami dla kontrybutorów. Utwórzmy gałąź feature/add-contribution-guide.

Krok 2. Wprowadź zmiany i wypchnij swoją gałąź na GitHub.

W nowej gałęzi utwórz plik CONTRIBUTING.md (po utworzeniu kliknij Add) i napisz w nim wiadomość do innych programistów. Następnie wykonaj Commit and Push z czytelnym komunikatem, na przykład: docs: Add contribution guide.

To kluczowy krok! Pull Request powstaje na podstawie gałęzi, która już istnieje na zdalnym serwerze. Dlatego, zanim utworzysz PR, musisz wypchnąć (push) swoją nową gałąź na GitHub.

3. Tworzenie Pull Requesta z IntelliJ IDEA

Skoro twoja gałąź jest już na GitHubie, możesz utworzyć Pull Request.

Krok 1. Otwórz kartę Pull Requests.

Po lewej stronie w IDE znajduje się karta Pull Requests. Otwórz ją i kliknij ikonę +, aby utworzyć nowy PR.

Krok 2. Wypełnij dane dla PR.

IDE automatycznie otworzy dla ciebie wygodny interfejs do tworzenia Pull Requesta. Twoim zadaniem jest poprawnie go wypełnić. Omówmy najważniejsze pola:

1. Tytuł: IDE często wstawia tu nazwę gałęzi, ale to zła praktyka. Tytuł powinien być krótki, zrozumiały i odzwierciedlać istotę zmian — jak dobra wiadomość commita.
2. Opis: tutaj wyjaśniasz, co i dlaczego zrobiłeś(-aś).
3. Recenzenci: tutaj wybierasz jednego lub kilku kolegów, którzy powinni sprawdzić twój kod. W projekcie szkoleniowym pominiemy ten krok, ale w realnej pracy jest obowiązkowy.
4. Wykonawcy: zwykle wskazujesz tu siebie. To oznacza, że jesteś autorem i główną osobą odpowiedzialną za to zadanie oraz za wprowadzanie poprawek po review.

Po wypełnieniu wszystkich pól śmiało kliknij Create Pull Request.

4. Code review: weryfikacja i dyskusja

Po utworzeniu PR zaczyna się najważniejszy etap — code review. Twoi koledzy mogą otworzyć twój PR, przejrzeć wszystkie zmiany i zostawić komentarze.

Wszystkie dyskusje możesz widzieć bezpośrednio w IDE, w karcie Pull Requests. Jeśli ktoś zostawi komentarz, otrzymasz powiadomienie.

Co zrobić, jeśli poproszono o poprawki?

Bardzo proste! Nie musisz tworzyć nowego PR. Po prostu wprowadź potrzebne zmiany w kodzie w tej samej gałęzi, zrób nowy commit i wypchnij go (push). Pull Request na GitHubie zaktualizuje się automatycznie, dodając twoje nowe commity.

5. Zakończenie pracy: scalenie i usunięcie gałęzi

Gdy wszystkie uwagi zostaną poprawione i zespół zaakceptuje twoje zmiany, Pull Request można scalać. Zwykle robi to starszy programista albo ty sam(a), jeśli masz uprawnienia.

Krok 1. Merge

Scalanie najczęściej odbywa się na stronie GitHub. Tam pod twoim PR pojawi się duży zielony przycisk Merge pull request. Po jego kliknięciu twój kod stanie się częścią głównej gałęzi main.

Krok 2. Usunięcie gałęzi.

Po scalen iu twoja gałąź `feature` nie jest już potrzebna i warto ją usunąć, aby nie zaśmiecać repozytorium. GitHub sam to zasugeruje, pokazując przycisk Delete branch.

Nie zapomnij również usunąć lokalnej kopii gałęzi w swoim IDE, aby utrzymywać porządek. Można to zrobić przez to samo menu zarządzania gałęziami.

6. Trzy zasady commitów

Dobry commit to nie tylko właściwa wiadomość, ale i właściwa zawartość. Aby historia zmian była czysta, użyteczna i profesjonalna, trzymaj się trzech prostych zasad.

Zasada 1: pisz zrozumiałe wiadomości zgodnie ze standardem

Twoje commity to wiadomości, które wysyłasz swojemu zespołowi i samemu sobie w przyszłość. Historia pełna komunikatów „fix” lub „update” jest zupełnie bezużyteczna. Najpopularniejszy standard nazywa się Conventional Commits. Proponuje on następującą strukturę:

<typ>: <krótki opis>

Typ — to krótkie słowo opisujące kategorię twoich zmian:

• feat: (feature) — dla nowej funkcjonalności.
• fix: — do naprawy błędu.
• docs: — do zmian w dokumentacji.
• style: — do poprawek formatowania, które nie wpływają na logikę kodu.
• refactor: — do zmian w kodzie, które nie dodają nowej funkcjonalności ani nie naprawiają błędów.
• test: — do dodawania lub poprawiania testów.
• chore: — do rutynowych zadań niezwiązanych z logiką kodu (aktualizacja zależności, konfiguracja procesu budowania).

Przykłady:

• Źle: fixed bug
• Dobrze: fix: Correct user login validation

• Źle: readme
• Dobrze: docs: Update installation instructions

Zasada 2: jeden commit — jedna logiczna zmiana (atomowość)

Nie próbuj upychać w jednym commicie naprawy błędu, dodania nowej funkcji i refaktoryzacji starego kodu. Taki commit bardzo trudno się przegląda i niemal niemożliwe jest bezboleśnie go wycofać, jeśli coś pójdzie nie tak.

Każdy commit powinien rozwiązywać tylko jedno konkretne zadanie.

• Źle: jeden commit z wiadomością „Update user page”, który dodaje pole dla awatara, naprawia błąd w walidacji nazwy użytkownika i zmienia kolor przycisków.
• Dobrze: trzy różne commity:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

Małe, skupione commity są znacznie prostsze do zrozumienia i zarządzania.

Zasada 3: commit nie może psuć projektu

Każdy commit w głównej gałęzi powinien zostawiać projekt w działającym stanie. Przed jego utworzeniem należy co najmniej upewnić się, że kod się kompiluje. Ale jak upewnić się, że przypadkiem nie zepsułeś czegoś w innej części systemu? Poleganie wyłącznie na ręcznej weryfikacji jest ryzykowne.

Tu z pomocą przychodzi automatyzacja. W tym kursie nie będziemy konfigurować automatycznych procesów, ale warto wiedzieć, jak działa to w prawdziwych projektach. Współczesne zespoły używają systemów ciągłej integracji (Continuous Integration, CI), takich jak GitHub Actions.

Jak to działa?

Piszesz kod i testy do niego. Następnie konfigurujesz specjalny scenariusz (workflow) bezpośrednio na GitHubie. Teraz, gdy tylko wykonasz push do swojego Pull Requesta, dzieje się magia:

1. GitHub Actions widzi to zdarzenie i uruchamia twój workflow.
2. Automatycznie „buduje” projekt i uruchamia wszystkie testy.
3. Jeśli wszystkie testy przejdą pomyślnie, obok twojego commita na GitHubie pojawi się zielony haczyk. To sygnał dla całego zespołu, że twoje zmiany są bezpieczne.
4. Jeśli chociaż jeden test się nie powiedzie, zobaczysz czerwony krzyżyk. Scalanie takiego PR do głównej gałęzi jest kategorycznie zabronione.

            graph LR
            subgraph GitHub
            A[Programista] -- "push" --> B(Repozytorium)
            B -- "Zdarzenie: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "Uruchomienie" --> D[Uruchomienie_testów]
            D --> E[Pomyślnie]
            D --> F[Niepowodzenie]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[Programista]
            G --> I[Zespół]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

Można skonfigurować powiadomienia. Jeśli testy się nie powiodą, GitHub Actions może wysłać e-mail do ciebie lub całego zespołu. Takie podejście tworzy kulturę, w której testy to nie tylko formalność, lecz integralna część wytwarzania oprogramowania, a każdy ponosi odpowiedzialność za jakość swojego kodu.