Pull requests pe GitHub

Pull request-ul (PR) nu e o funcție a Git-ului, ci a platformelor de găzduire. Este locul unde munca ta devine vizibilă, e discutată și abia apoi intră în main. În echipe, PR-ul e cel mai important obicei de calitate — mai important decât orice comandă din acest curs.

Fluxul complet

1. Pleci de la un main actualizat și deschizi un branch.
2. Lucrezi, faci commit-uri, dai push branch-ului.
3. Deschizi un pull request de la branch-ul tău către main.
4. Colegii comentează; tu faci commit-uri noi în același branch, care apar automat în PR.
5. După aprobare, PR-ul e integrat și branch-ul se șterge.

git switch main && git pull
git switch -c fix/eroare-la-salvarea-comenzii
# ... modificări, commit ...
git push -u origin fix/eroare-la-salvarea-comenzii

După push, Git îți afișează chiar în terminal un link direct de creare a PR-ului.

Cum scrii un pull request pe care lumea vrea să-l revizuiască

Un PR bun economisește timpul reviewerului. Structura care funcționează:

• Titlu — ce face schimbarea, nu pe ce ai lucrat: „Repară eroarea 500 la salvarea comenzii cu cupon expirat".
• Context — ce problemă rezolvă, cu link către tichet dacă există.
• Ce am schimbat — trei-cinci puncte, nu lista fișierelor (aceea se vede oricum).
• Cum se testează — pașii concreți pentru cineva care nu a atins codul.
• Capturi de ecran — obligatorii pentru orice schimbare vizuală.
• Riscuri — ce ar putea să se rupă, ce trebuie urmărit după deploy.

Dacă scrii în descriere Closes #42, GitHub închide automat tichetul 42 când PR-ul este integrat.

Mărimea contează

Un PR de 2.000 de linii nu primește review, primește „LGTM" (looks good to me) fără ca nimeni să se fi uitat serios. Un PR de 200 de linii primește observații reale.

Dacă o funcționalitate e mare, împarte-o: întâi migrarea de bază de date, apoi logica, apoi interfața. Fiecare bucată trebuie să funcționeze singură.

Cum răspunzi la review

Reviewerul comentează pe linii. Tu ai trei reacții legitime: accepți și modifici, explici de ce ai făcut altfel, sau propui o a treia variantă. Ce nu faci: iei comentariul personal.

# faci modificările cerute în același branch
git add .
git commit -m "Extrage validarea cuponului în clasă separată"
git push

PR-ul se actualizează singur. Nu deschizi un PR nou pentru corecturi.

Cele trei moduri de integrare

La butonul de merge, GitHub îți dă trei opțiuni, cu efecte diferite asupra istoricului:

• Merge commit — păstrează toate commit-urile tale plus un commit de merge. Istoric complet, dar stufos.
• Squash and merge — topește tot PR-ul într-un singur commit pe main. Cea mai populară alegere: main rămâne curat, un commit = o funcționalitate.
• Rebase and merge — pune commit-urile tale la capătul lui main, fără merge commit. Istoric liniar, dar pierzi gruparea pe PR.

Dacă echipa nu are o preferință, squash and merge e alegerea sigură.

Protejarea branch-ului main

Într-un repository serios, main este protejat din Settings → Branches. Setările care merită activate:

• interzice push-ul direct în main;
• cere cel puțin o aprobare înainte de merge;
• cere ca testele automate (CI) să treacă;
• cere ca branch-ul să fie la zi cu main înainte de integrare.

Astfel, regula „nu lucrăm direct pe main" nu mai depinde de disciplina fiecăruia.

Cum faci tu un review bun

Mai devreme sau mai târziu vei fi de cealaltă parte. Un review util respectă câteva reguli simple:

• Separă obligatoriul de preferință. Marchează clar: „blocant" pentru ce trebuie schimbat, „sugestie" pentru ce ar fi frumos. Altfel autorul nu știe ce e negociabil.
• Comentează codul, nu omul. „Aici se poate face o injecție SQL" e util. „Nu înțelegi cum funcționează" nu e.
• Întreabă când nu înțelegi în loc să presupui că e greșit. Adesea răspunsul e un context pe care nu-l aveai.
• Verifică ce lipsește, nu doar ce e scris: tratarea erorilor, cazurile limită, testele, ce se întâmplă la valori goale.
• Aprobă când e suficient de bun. Un PR nu trebuie să fie perfect, trebuie să fie mai bun decât ce era.

Pe GitHub ai trei verdicte: Comment (observații fără decizie), Approve și Request changes. Ultimul blochează integrarea, deci folosește-l pentru probleme reale, nu pentru spații.

Automatizări care fac review-ul mai ușor

O parte din comentariile clasice („ai uitat un punct și virgulă", „formatarea nu respectă standardul") nu ar trebui făcute de oameni. Le poți muta în GitHub Actions, adică într-un fișier .github/workflows/ci.yml care rulează la fiecare push:

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
      - run: composer install --no-interaction
      - run: php artisan test

Rezultatul apare direct în PR, cu bifă verde sau roșie. Combinat cu regula „nu se face merge dacă testele pică", ai o plasă de siguranță care nu depinde de atenția nimănui.

Contribuția la proiecte open source

La proiectele unde nu ai drept de scriere, fluxul are un pas în plus: faci fork (o copie a repository-ului în contul tău), lucrezi acolo și deschizi PR dinspre fork către proiectul original.

git clone https://github.com/contul-tau/proiect.git
cd proiect
git remote add upstream https://github.com/proiect-original/proiect.git

# ca să te menții la zi cu proiectul original
git fetch upstream
git merge upstream/main

Înainte să deschizi PR-ul, citește CONTRIBUTING.md. Multe PR-uri sunt respinse nu pentru cod, ci pentru că nu au respectat convențiile casei.

Exercițiu

1. Creează un repository pe GitHub și activează protecția pe main (cere PR înainte de merge).
2. Deschide un branch, fă o modificare mică și creează un PR cu descriere completă: context, ce ai schimbat, cum se testează.
3. Lasă-ți singur un comentariu de review pe o linie, apoi rezolvă-l cu un commit nou.
4. Integrează PR-ul cu „Squash and merge" și verifică ce a apărut în istoricul lui main.

Documentație și surse

• Pro Git — Git