Magia Pull Requests

1. Od scalania do propozycji: po co są Pull Requests?

W 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 lub usunąć ważną część pracy kolegi.

Aby tego uniknąć, w pracy zespołowej przyjmuje się inny sposób. Zamiast od razu scalać zmiany, tworzysz propozycję na scalenie. Ta propozycja nazywa się Pull Request (w skrócie PR) albo na niektórych platformach Merge Request.

Pull Request — to oficjalna prośba: "Proszę, pobierz (pull) moje zmiany z mojej gałęzi i dodaj (merge) je do głównej gałęzi". Ale to nie tylko prośba, to całe miejsce do dyskusji, przeglądu i ulepszania kodu, zanim trafi do main.

2. Standardowy workflow z Pull Request

Przejdźmy krok po kroku, jak wygląda typowy proces pracy przy dodawaniu nowej funkcjonalności.

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

W przeciwnym razie wszystkie twoje "zapomniane" lokalne commity z main mogą przypadkowo trafić do nowego Pull Request i wprowadzić zamieszanie wśród kolegów.

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

Jak wcześniej, każda nowa praca zaczyna się od utworzenia oddzielnej gałęzi. Załóżmy, że chcemy dodać do projektu plik z zasadami dla contributorów. Stwó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 stworzeniu kliknij Add) i napisz w nim wiadomość do innych developerów. Potem zrób Commit and Push z zrozumiałym komunikatem, na przykład: docs: Add contribution guide.

To kluczowy krok! Pull Request tworzy się 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 Request z IntelliJ IDEA

Teraz, kiedy twoja gałąź jest na GitHub, możesz stworzyć Pull Request.

Krok 1. Otwórz zakładkę Pull Requests.

Po lewej w IDE jest zakładka Pull Requests. Otwórz ją i kliknij ikonę +, żeby utworzyć nowy PR.

Krok 2. Wypełnij dane dla PR.

IDE automatycznie otworzy wygodny interfejs do tworzenia Pull Request. Twoim zadaniem jest mądre jego wypełnienie. Omówmy podstawowe pola:

1. Tytuł: IDE często podpowiada tutaj nazwę gałęzi, ale to zła praktyka. Tytuł powinien być krótki, zrozumiały i odzwierciedlać sedno zmian, jak dobre commit message.
2. Opis: tutaj wyjaśniasz, co i dlaczego zrobiłeś.
3. Reviewers: tu wybierasz jednego lub kilku kolegów, którzy mają sprawdzić twój kod. W projekcie edukacyjnym pominiemy ten krok, ale w realnej pracy jest on obowiązkowy.
4. Assignees: zazwyczaj wpisujesz siebie. To znaczy, że jesteś autorem i główną osobą odpowiedzialną za to zadanie i wprowadzenie poprawek po review.

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

4. Code-review: przegląd i dyskusja

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

Możesz widzieć wszystkie dyskusje bezpośrednio w IDE w zakładce Pull Requests. Jeśli ktoś zostawi komentarz, dostaniesz powiadomienie.

Co robić, jeśli poproszą o poprawki?

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

5. Zamknięcie pracy: merge i usunięcie gałęzi

Kiedy wszystkie uwagi zostaną poprawione i zespół zatwierdzi zmiany, Pull Request można scalić. Zwykle robi to senior developer albo ty sam, 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 kliknięciu twój kod stanie się częścią głównej gałęzi main.

Krok 2. Usunięcie gałęzi.

Po sca leniu twoja gałąź `feature` nie jest już potrzebna i warto ją usunąć, żeby nie zaśmiecać repozytorium. GitHub sam zaproponuje to zrobić, pokazując przycisk Delete branch.

Nie zapomnij też usunąć lokalnej kopii gałęzi w swoim IDE, żeby utrzymać porządek. Można to zrobić z tego samego menu zarządzania gałęziami.

6. Trzy zasady commita

Dobry commit to nie tylko poprawny komunikat, ale też właściwa zawartość. Żeby twoja historia zmian była czysta, użyteczna i profesjonalna, trzymaj się trzech prostych zasad.

Zasada 1: pisz czytelne komunikaty zgodnie ze standardem

Twoje commity to wiadomości, które wysyłasz zespołowi i sobie w przyszłości. Historia pełna komunikatów "fix" lub "update" jest praktycznie bezużyteczna. Najpopularniejszy standard to Conventional Commits. Proponuje następującą strukturę:

<typ>: <krótkie opisanie>

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

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

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 zmieścić w jednym commicie naprawy bug'a, dodania nowej funkcji i refaktoryzacji starego kodu. Taki commit jest trudny do przeglądania i niemal niemożliwy do bezbolesnego odwrócenia, jeśli coś pójdzie nie tak.

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

• Źle: jeden commit z komunikatem "Update user page", który dodaje pole na avatar, naprawia walidację 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, sfokusowane commity są dużo łatwiejsze do zrozumienia i zarządzania.

Zasada 3: Commit nie powinien łamać projektu

Każdy commit w głównej gałęzi powinien pozostawić projekt w działającym stanie. Zanim go zrobisz, powinieneś przynajmniej upewnić się, że kod się kompiluje. Ale jak być pewnym, że przypadkowo nie zepsułeś czegoś w innej części systemu? Poleganie tylko na ręcznej kontroli jest ryzykowne.

Tu z pomocą przychodzi automatyzacja. Na tym kursie nie będziemy konfigurować automatów, ale warto wiedzieć, jak to działa w realnych 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 GitHub. Teraz, kiedy wypchniesz push do swojego Pull Request, dzieje się magia:

1. GitHub Actions wykrywa to zdarzenie i uruchamia twój scenariusz.
2. On automatycznie "buduje" projekt i uruchamia wszystkie testy.
3. Jeśli wszystkie testy przejdą pomyślnie, obok twojego commita na GitHub pojawi się zielony znaczek. To sygnał dla całego zespołu, że twoje zmiany są bezpieczne.
4. Jeśli przynajmniej jeden test polegnie, zobaczysz czerwony krzyżyk. Scalanie takiego PR do głównej gałęzi jest kategorycznie zabronione.

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

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

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

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

Można ustawić powiadomienia. Jeśli testy nie przejdą, GitHub Actions może wysłać maila do ciebie albo do całego zespołu. Takie podejście buduje kulturę, w której testy to nie tylko formalność, ale nieodłączna część tworzenia oprogramowania, i każdy odpowiada za jakość swojego kodu.