Scrierea unei descrieri bune Pull Request este una dintre cele mai obositoare sarcini pe care trebuie să le facă un dezvoltator. Și uneori se poate simți contraproductiv.

Dar dezvoltarea acestei abilități merge mult și ajută cu adevărat părțile interesate și organizația dvs. pe termen lung.

Deci, este întotdeauna mai bine să puneți acele 10 minute în plus astăzi, mai degrabă decât să vă rupeți capul 6 luni pe drum încercând să explicați de ce ați făcut ce ați făcut.

Următorul articol explică diferitele părți ale unei descrieri a cererii de extragere și de ce ar trebui să le includeți.

Ce este o descriere PR?

O descriere a cererii de extragere descrie ceea ce constituie cererea de extragere și ce modificări ați făcut codului.

Acesta explică ceea ce ați făcut, inclusiv orice modificări de cod, modificări de configurare, migrări incluse, noi API-uri introduse, modificări aduse API-urilor vechi, orice lucrători / croni noi introduși în sistem, modificări de copiere și așa mai departe. Ai înțeles.

Ar trebui să includeți această secțiune, deoarece oferă o privire asupra diferitelor părți interesate în ceea ce face PR.

Pentru o persoană non-tehnică, descrierea ar trebui să explice care va fi impactul asupra sistemului atunci când aceste modificări de cod sunt implementate în producție.

De asemenea, îl va ajuta pe recenzor să înțeleagă ce vor revizui (un fel de prolog / trailer).

Și, în cele din urmă, ajută QA / SDET să înțeleagă și domeniul de aplicare al PR.

Deci „ce” din PR ar trebui să arate o privire asupra a ceea ce constituie schimbările din PR.

Secțiunea „De ce”

Această secțiune explică de ce s-au făcut modificările de mai sus.

Uneori, un dezvoltator consideră că este în regulă să scrie „Cerința companiei / produsului” în descriere. Este în regulă, dar acest lucru învinge scopul acestei secțiuni.

Dacă există o explicație mai bună cu privire la motivele pentru care au fost sugerate modificările, este întotdeauna bine să atașați un link de referință a documentului pentru acele informații. O bună secțiune „De ce” ar trebui să explice raționamentul din spatele oricăror modificări.

Ar trebui să includeți această secțiune, deoarece oferă o explicație a motivelor pentru care ați sugerat modificările dvs. S-ar putea să nu pară rezonabil să incluzi această secțiune pe termen scurt, dar joacă un rol vital pe măsură ce produsul se maturizează și se întinde pe ani.

Dezvoltatorii / Produsele vin și pleacă, dar codul rămâne. Și atunci când un dezvoltator nou lucrează la o bucată de cod și găsește o discrepanță acolo, ei pot săpa mai adânc și să ajungă la cererea de extragere de acum 2 ani care a făcut acele modificări.

Un „de ce” bun le oferă explicația și presupunerile făcute în acel moment.

CTO-ul lui GoJek a explicat odată că nu își contestă vechiul cod și nu pun la îndoială de ce pare să existe o caracteristică absurdă în produs.

Se întorc și verifică documentația.

Ipotezele și circumstanțele s-ar fi putut schimba și, prin urmare, codul evoluează. Ceea ce pare a fi destul de absurd astăzi ar fi putut fi relevant acum 2 ani. Deci, este mai bine să explicați astăzi de ce faceți o anumită schimbare.

Domeniul de testare

Această secțiune ar trebui să cuprindă o listă de scenarii pe care trebuie să le urmăriți atunci când testați acest PR special. (Aceasta va include fluxurile, API-urile, cronii, lucrătorii etc.)

Un domeniu bun de testare oferă vizibilitate echipei QA / SDET cu privire la scenariile și fluxurile pe care trebuie să le testeze.

De asemenea, vă poate ajuta în timp ce scrieți această secțiune. Am întâlnit eu însumi probleme, ceea ce m-a determinat să mă întorc la faza de dezvoltare și să le testez din nou.

Un domeniu de testare complet scris îi ajută pe dezvoltatori să testeze PR mai eficient și oferă o imagine detaliată a PR-ului persoanei care îl testează.

Documente relevante)

Această secțiune include orice document relevant care trebuie atașat la descrierea PR.

Acestea ar putea include documente privind cerințele produsului, diagrame arhitecturale, diagrame ale sistemului de baze de date, modele de proiectare utilizate, diagrame de clasă, documentație de bibliotecă externă și așa mai departe.

Această secțiune vă explică orice presupuneri și referințe pe care le-ați făcut în timp ce lucrați la această solicitare de caracteristică. Și joacă un rol major pe termen lung.

Când cineva se întoarce și vede de ce a fost sugerată o astfel de modificare, secțiunea de documente relevante îi va duce la documentația specifică, astfel încât să poată înțelege problema în mod clar. Sau îi poate duce la detaliile tehnice de implementare ale scenariului în momentul dezvoltării.

PR (uri) dependente (dacă există)

Există momente în care o anumită caracteristică se întinde pe mai multe depozite GitHub și este important să le eliberați într-o anumită ordine.

De exemplu, este posibil să trebuiască să implementați o repo înainte de alta sau să fie necesar să le implementați una lângă alta.

Indiferent de caz, această secțiune explică orice cod dependent pe care se bazează acest PR.

Ar trebui să includeți această secțiune, deoarece într-adevăr ajută implementatorul să înțeleagă ordinea de desfășurare. În cazul în care codul unei alte repo-uri trebuie să meargă mai întâi, atunci implementatorul va contacta persoana responsabilă pentru implementarea celeilalte repo-uri pentru a se asigura că implementarea lor are loc mai întâi. În general, ajută la fluidizarea procesului de implementare.

Modificări de configurare (dacă există)

Această secțiune ar trebui să includă toate modificările de configurare care trebuie adăugate secretelor înainte ca PR să fie implementat în producție.

Vor fi momente când implementatorul va îmbina 10-20 PR-uri la un moment dat și le devine greu să țină evidența tuturor modificărilor de configurare.

Din această cauză, este întotdeauna mai bine să le includeți în secțiunea de modificări de configurare. (Nu puneți cheile secrete acolo, includeți doar numele cheilor și cum să obțineți secretele.)

Etichete / Etichete

Acestea sunt foarte importante într-o descriere a cererii de extragere și transmit multă semnificație atunci când echipa crește.

Următoarele sunt câteva etichete pe care le folosesc, dar puteți adăuga etichete diferite în funcție de nevoile dvs.

  • Dezvoltare finalizată – Când dezvoltarea este finalizată din partea dezvoltatorului.
  • Autorevaluat – Când dezvoltatorii (solicitanții) Pull Request au examinat din partea lor cererea Pull și o pot da acum colegilor lor pentru o evaluare inter pares.
  • Autotestat – Atunci când dezvoltatorii (solicitanții) cererii de extragere au testat modificările în conformitate cu descrierea pe care au dat-o în secțiunea Domeniu de testare.
  • Modificări de configurare – Această etichetă indică faptul că există unele modificări de configurație care trebuie făcute înainte de a implementa PR în producție. (Aceasta include chei secrete care trebuie introduse în sistem.)
  • Conține migrație (e) – Acest lucru indică faptul că PR conține o migrare. Dacă este o migrare de lungă durată, ar trebui specificată în prealabil.
  • Gata de lansare – Acest lucru indică implementatorului că PR este pregătit pentru implementare și va fi preluat de acesta în următorul ciclu de implementare.
  • Evaluat de colegi – Când Peer-ul a examinat PR-ul și modificările sugerate sunt făcute de dezvoltator (i). Acest lucru este susținut de colegul care a analizat PR.
  • QA testat – Acest lucru indică faptul că QA / SDET a testat PR și este bine să fie implementat în producție.

Concluzie

În acest articol, am parcurs diferitele părți ale unei descrieri PR. Majoritatea PR-urilor pe care le faceți nu vor avea nevoie de toate aceste secțiuni și etichete, dar ar trebui să încercați să includeți cât mai multe dintre ele.

Scrierea acestei descrieri s-ar putea să nu pară productivă în momentul în care creați un PR, dar cu siguranță se poate dovedi utilă în viitor.

O notă finală: cele de mai sus sunt opiniile mele și ar putea diferi de perspectiva dvs. Dar am dezvoltat această strategie de-a lungul anilor și conține contribuția și experiența multor oameni cu care am lucrat în industrie. Deci, vă puteți simți bine știind că a fost testat la luptă într-un grad înalt.