Pull request-uri, de la creare la merge

În acest articol veți afla ce este un Pull Request (PR), de ce este un instrument pentru discutarea modificărilor și cum puteți crea și examina un PR direct din IDE. Vom trece și prin trei reguli pentru commit-uri bune. E o bază importantă: Claude Code poate pregăti și comenta pull request-uri în locul dumneavoastră, iar ca să-l folosiți în cunoștință de cauză, trebuie să înțelegeți ce este un PR și la ce folosește.

Exemplele și capturile de interfață sunt din IDE-ul JetBrains; denumirile și poziția acțiunilor pot diferi în versiunea dumneavoastră. Pentru exerciții, folosiți un repository separat, de studiu. Într-un proiect de lucru, respectați regulile acestuia privind branch-urile, commit-urile și trimiterea modificărilor.

La ce folosesc Pull Request-urile

Într-o echipă, e util să discutați modificările înainte să ajungă în branch-ul comun. Pull request-ul reunește într-un singur loc diff-ul propus, observațiile și rezultatele verificărilor. Se folosește și în proiecte personale, ca să vă verificați propria muncă înainte de merge.

Într-un flux de lucru cu PR, mai întâi creați o propunere de merge. Pe GitHub se numește Pull Request, iar pe unele alte platforme poate apărea ca Merge Request. Echipa stabilește procesul concret.

Pull Request este o cerere oficială: "preluați (pull), vă rog, modificările mele din branch-ul meu și integrați-le (merge) în branch-ul principal". Dar nu e doar o cerere, ci și un spațiu în care codul poate fi discutat, verificat și îmbunătățit înainte să ajungă în main.

Fluxul obișnuit de lucru cu Pull Request

Iată, pas cu pas, cum arată procesul obișnuit când dezvoltați o funcționalitate nouă.

Înainte să creați un branch, verificați branch-ul de pornire și lista commit-urilor lui în raport cu branch-ul țintă de pe GitHub. Într-un PR nou nu trebuie să ajungă commit-uri locale fără legătură cu schimbarea. Nu le trimiteți automat doar pentru "sincronizare": alegeți baza corectă pentru sarcină și păstrați separat lucrul început anterior.

Pasul 1. Creați un branch pentru sarcina nouă. În procesul PR din acest exemplu, lucrul începe într-un branch separat. Să presupunem că vrem să adăugăm un fișier cu reguli pentru colaboratori - creăm branch-ul feature/add-contribution-guide.

Pasul 2. Faceți modificările și trimiteți branch-ul pe GitHub. În branch-ul nou, creați fișierul CONTRIBUTING.md (după creare, apăsați Add) și scrieți un mesaj pentru ceilalți dezvoltatori. Apoi folosiți Commit and Push cu un mesaj clar, de exemplu docs: Add contribution guide.

Acesta e pasul esențial. Pull Request-ul se creează pe baza unui branch care există deja pe serverul la distanță. De aceea, înainte să creați PR-ul, trimiteți neapărat branch-ul nou (push) pe GitHub.

Crearea unui Pull Request din IDE

Verificați ambele părți ale comparației: base este branch-ul care primește modificările, iar compare/head este branch-ul în care ați lucrat. Examinați lista de commit-uri și diff-ul înainte să creați PR-ul.

Acum că branch-ul este pe GitHub, puteți crea Pull Request-ul.

Pasul 1. Deschideți fila Pull Requests. În bara laterală din stânga a IDE-ului, găsiți fila Pull Requests. Deschideți-o și apăsați pictograma + (sau butonul Create Pull Request).

Pasul 2. Completați detaliile PR-ului. IDE-ul va deschide o interfață comodă. Completați câmpurile cu grijă. Iată-le pe cele principale:

1. titlul - IDE-ul completează adesea acest câmp cu numele branch-ului sau cu mesajul ultimului commit; verificați să fie scurt, clar și să descrie modificările;
2. descrierea - explicați-le colegilor în detaliu ce anume ați făcut și de ce;
3. reviewerii (Reviewers) - persoanele cărora le cereți să verifice modificările. Regulile repository-ului stabilesc dacă aprobarea lor este obligatorie;
4. responsabilii (Assignees) - de obicei vă treceți aici pe dumneavoastră, ca autor și responsabil pentru modificările de după review.

Înainte de Create Pull Request, verificați încă o dată base, head și diff-ul. Dacă munca nu e gata pentru review, puteți crea un Draft PR, atunci când opțiunea este disponibilă. Atât PR-ul obișnuit, cât și ciorna sunt deja vizibile persoanelor care au acces la repository.

Code review - verificare și discuție

După crearea PR-ului începe etapa cea mai importantă - code review. Colegii pot deschide PR-ul, examina toate modificările și lăsa comentarii.

Toate discuțiile sunt vizibile direct în IDE, în fila Pull Requests. Dacă cineva comentează o linie de cod, veți primi o notificare și îi puteți răspunde fără să treceți în browser.

Ce faceți dacă vi se cer modificări? E simplu: nu creați un PR nou. Modificați codul în branch-ul inițial al acestui PR, creați un commit nou și trimiteți-l. Pull Request-ul de pe GitHub se va actualiza automat, adăugând noile commit-uri la discuția existentă.

Încheierea lucrului - merge și ștergerea branch-ului

După ce rezolvați toate observațiile și echipa aprobă modificările (primiți un "approval"), puteți face merge la Pull Request. De obicei, de asta se ocupă un dezvoltator senior sau chiar dumneavoastră, dacă aveți drepturile necesare în repository.

Pasul 1. Faceți merge. Verificați observațiile, aprobările obligatorii și starea verificărilor. Dacă regulile și permisiunile permit, alegeți metoda disponibilă (merge, squash sau rebase) conform regulilor proiectului și confirmați. Modificările vor ajunge în branch-ul țintă al PR-ului, în exemplul nostru main.

Pasul 2. Ștergeți branch-ul. După merge, branch-ul feature nu mai este necesar; merită să-l ștergeți ca să nu aglomereze repository-ul. GitHub vă va propune acest lucru prin butonul Delete branch.

După merge, treceți local la main, preluați actualizările și verificați că modificările PR-ului sunt acolo. Apoi puteți șterge branch-ul local al sarcinii, dacă nu mai conține lucru necesar. Dacă IDE-ul nu vă lasă să-l ștergeți în mod obișnuit, aflați mai întâi de ce, mai ales după squash sau rebase.

Trei reguli pentru commit-uri bune

Un commit bun înseamnă nu doar un mesaj potrivit, ci și un conținut corect. Ca istoricul modificărilor să rămână clar și util, țineți cont de trei reguli simple.

Regula 1 - scrieți mesaje clare

Commit-urile sunt mesaje pentru echipă și pentru dumneavoastră, în viitor. Un istoric plin doar de "fix" sau "update" nu ajută pe nimeni. Un format răspândit este Conventional Commits, care propune următoarea structură:

<tip>: <descriere scurtă>

Tipul este un cuvânt scurt care descrie categoria modificărilor:

• feat - funcționalitate nouă;
• fix - repararea unei erori;
• docs - modificări în documentație;
• style - modificări de formatare, fără impact asupra logicii;
• refactor - modificări de cod fără funcționalitate nouă și fără repararea unor erori;
• test - adăugarea sau repararea testelor;
• chore - sarcini de rutină (actualizarea dependențelor, configurarea build-ului).

Exemple:

• Greșit: fixed bug
• Corect: fix: Correct user login validation
• Greșit: readme
• Corect: docs: Update installation instructions

Regula 2 - un commit, o singură modificare logică

Nu încercați să includeți într-un singur commit repararea unui bug, o funcție nouă și refactoringul codului vechi. Un astfel de commit e greu de verificat la review și aproape imposibil de anulat fără efecte secundare. Fiecare commit trebuie să rezolve o singură problemă concretă.

• Greșit: un singur commit "Update user page" care adaugă un câmp pentru avatar, repară validarea numelui și schimbă culoarea butoanelor;
• Corect: trei commit-uri separate:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. feat: Update button colors on user page

Dacă, pe parcurs, ați modificat prea multe lucruri într-un fișier, IDE-ul vă permite să creați un commit doar cu o parte din el: în fereastra Commit, extindeți fișierul și bifați doar fragmentele (chunks) care țin de sarcina respectivă.

Regula 3 - verificați rezultatul modificărilor

Înainte de merge, rulați verificările potrivite pentru modificare și examinați rezultatele obținute. Verificările diferă pentru o modificare de documentație și pentru o logică nouă.

Dacă repository-ul are deja verificări automate configurate, PR-ul le afișează starea. Marcajul verde arată că verificările rulate au trecut, dar nu dovedește că nu există erori. Uitați-vă ce s-a executat și ce a rămas neverificat. Configurarea automatizării e un subiect separat.

Cum funcționează împreună cu Claude Code

PR-ul este un loc în care Claude Code se dovedește deosebit de util. Iată la ce să fiți atenți:

• Claude poate crea un pull request pentru branch-ul dumneavoastră, cu titlul și descrierea pregătite - verificați textul înainte ca PR-ul să fie creat pe GitHub;
• poate examina modificările PR-ului și lăsa comentarii, ca primă verificare;
• vă poate ajuta să formulați mesajele commit-urilor conform regulilor proiectului;
• vă poate ajuta să interpretați rezultatele verificărilor deja configurate și să identificați ce a rămas neverificat.

Articolul anterior: Ramuri și îmbinări în Git · Articolul următor: Anularea și recuperarea modificărilor în Git