3.5 PR leírás megírása

← 3. Code review kultúra és készségek

3.5 PR leírás megírása – hogy ne kelljen mindent megkérdezni

Áttekintő

Egy jó Pull Request leírás időt spórol neked és a reviewernek egyaránt. Ha a PR-odhoz odaírod, miért csináltad, mit teszteltél, és van-e mellékhatás, a reviewer nem fog visszakérdezni – azonnal el tud indulni. Ez a szekció megmutatja, mi kerüljön egy PR leírásba, és miért csinálja ezt szinte mindenki rosszul az elején.

Részletes leírás

Miért fontos a PR leírás?

A legtöbb junior fejlesztő úgy nyit PR-t, hogy a leírás üres – vagy egy sornyi, például: „fix bug", „new feature", „changes". A következmény: a reviewer kénytelen megkérdezni, mi változott és miért, ami:

  • lelassítja a review folyamatot (különösen eltérő időzónák esetén),
  • frusztrációt okoz a senior kollégáknak,
  • rossz benyomást kelt rólad mint szerzőről.

A jó PR leírás egy aszinkron kommunikációs eszköz: olyan, mintha ott lennél, és elmagyaráznád a kódodat – de mindezt előre megírod, hogy a reviewer a saját idejében olvasni tudja.

Mi kerüljön a PR leírásba?

Nincs egyetlen kötelező sablon, de az alábbi elemek általában minden PR-ban relevánsak:

1. Miért csináltad? (Context / Motivation)

A legfontosabb rész. Mit old meg ez a PR? Melyik ticket-hez kapcsolódik? Mi az a probléma, amit ez a változtatás kezel?

## Miért?
Closes #142

A felhasználói profiloldalon a „Mentés" gomb aktív maradt, 
ha nem változott semmi. Ez félrevezető UX volt.

A ticket száma önmagában nem elegendő! Sokan nem fogják felütni, és az sem mindig egyértelmű a ticketből, miért így és nem másképp oldottad meg.

2. Mit változtattál? (What changed)

Tömör, de konkrét leírás. Ha sok a változtatás, struktúrálj bullet pontokkal.

## Mit változtattál?
- Hozzáadtam egy `isDirty` állapotot a form komponenshez
- A „Mentés" gomb csak akkor aktív, ha `isDirty === true`
- Egységtesztet írtam mindkét állapotra

3. Mit teszteltél? (Testing)

Ez az a pont, amit a leggyakrabban kihagynak a juniorok – és ami a reviewernek a legtöbbet segít.

## Tesztelés
- [x] Manuálisan teszteltem Chromeben és Firefoxban
- [x] Egységtesztek futnak: `npm test`
- [x] Kipróbáltam szerkesztés nélküli mentést → gomb szürke
- [x] Kipróbáltam szerkesztés utáni mentést → gomb aktív, mentés sikeres

4. Van-e mellékhatás / kockázat? (Side effects / Risks)

Ha valamit megváltoztattál, ami más részre hatással lehet, írd le.

## Mellékhatások
- A `ProfileForm` komponenst kisebb mértékben refaktoráltam, 
  ez érintheti a `EditPage`-et is (átnéztem, nem okoz problémát).

Ha nincs mellékhatás: „Nincs ismert mellékhatás." – ez is értékes információ.

5. Screenshot (ha UI változás)

Ha megváltozott valami vizuálisan, csatolj képet. Előtte/utána formátum ideális. Ez rengeteg szót helyettesít.

## Képernyőképek
**Előtte:** [screenshot]
**Utána:** [screenshot]

PR leírás sablonok a valóságban

Sok csapat és projekt GitHub-on egy .github/pull_request_template.md fájlt használ – ez automatikusan kitölti a PR leírás mezőjét egy sablonnal, amikor új PR-t nyitsz. Ha a projektedben van ilyen, kötelező kitölteni. Ha nincs, a fenti elemek mentén saját magad struktúráld.

A reviewer szemszögéből

Képzeld el, hogy egy PR-t kapsz review-ra. Az alábbi két változat közül melyikkel szeretnél dolgozni?

PR A:

leírás: refactor

PR B:

## Miért?
A user service túl sok felelősséget kapott, nehezen volt tesztelhető.
Closes #88

## Mit változtattál?
- UserService-ből kiemeltem a NotificationService-t
- Hozzáadtam interfészt a könnyebb mockoláshoz
- 4 meglévő tesztet frissítettem

## Tesztelés
- [x] Minden meglévő teszt zöld
- [x] Manuálisan teszteltem regisztrációs email küldést

## Mellékhatás
- A NotificationService önálló service lett, DI containerben regisztrálni kell
  (a config fájlt frissítettem)

PR B esetén a reviewer egy kör kérdezés nélkül tud dolgozni. PR A esetén valószínűleg visszakérdez – ami egy napot is csúsztathat a review-n.

Amit sokan félreértenek

„Ez csak egy kis változtatás, nem kell leírás."
Kis PR is igényel kontextust. Miért pont most? Miért így? Egy mondat is elegendő – de az a mondat sokat ér.

„Ott van a commit üzenetben."
A PR leírás más célra való. A commit üzenet az adott commit kontextusát írja le; a PR leírás az egész változtatáscsomag célját és hatását foglalja össze.

„Majd szóban megmagyarázom."
Aszinkron csapatok esetén ez nem opció. Időzóna-különbség, delayed review, dokumentálhatóság – mind a leírás mellett szól.

Életszerű példák

Példa 1 – Feature PR (Python/Django backend)

## Miért?
Closes #201

A felhasználók nem kaptak visszajelzést, ha a jelszócsere sikertelen volt – 
a form újra üres lett, hibaüzenet nélkül.

## Mit változtattál?
- `change_password` view-ban hozzáadtam validációs hibakezelést
- A sablon megjeleníti a hibaüzeneteket a form felett
- Unit tesztet írtam hibás és helyes jelszócsere esetekre

## Tesztelés
- [x] `python manage.py test accounts.tests`
- [x] Manuálisan teszteltem: nem egyező jelszó → hibaüzenet megjelenik
- [x] Helyes jelszó → sikeres átirányítás

## Mellékhatás
Nincs ismert mellékhatás.

Példa 2 – Bugfix PR (JavaScript/Node.js)

## Miért?
Closes #317

Production-ban előfordult, hogy a `getUser` endpoint 500-as hibával tért vissza, 
ha a `userId` undefined volt. Ez nem volt kezelve.

## Mit változtattál?
- Input validációt adtam a `getUser` controllerhez
- Ha a `userId` hiányzik vagy érvénytelen, 400-as hibát adunk vissza
- Tesztet írtam a hiányzó és érvénytelen ID esetekre

## Tesztelés
- [x] `npm test` – minden teszt zöld
- [x] Postman-nel manuálisan teszteltem: hiányzó ID → 400, érvényes ID → 200

## Mellékhatás
Nincs – a validáció csak az újonnan kezelt esetekre lép be.

Példa 3 – Refactor PR (PHP/Laravel)

## Miért?
Nem kapcsolódik tickethez – technikai adósság csökkentése.

Az `OrderController` ~400 soros volt, az üzleti logika közvetlenül a controllerben 
volt. Ez tesztelési és karbantartási problémát okozott.

## Mit változtattál?
- Létrehoztam `OrderService` osztályt az üzleti logikával
- A controller most csak a kérést/választ kezeli
- A meglévő feature tesztek változatlanul futnak

## Tesztelés
- [x] `php artisan test` – 47 teszt, mind zöld
- [x] Manuálisan átteszteltem a rendelési folyamatot dev környezetben

## Mellékhatás
- Az `OrderService`-t a service containerbe regisztrálni kell – 
  ezt a `AppServiceProvider`-ben elvégeztem.

Tesztfeladatok

1. kérdés
Mi a PR leírás elsődleges célja?

a) A változtatások részletes technikai dokumentációja
b) Aszinkron kommunikáció – a reviewer megkapja a szükséges kontextust kérdezés nélkül
c) A ticket tartalmának másolása a PR-ba
d) A commit üzenetek összefoglalása

2. kérdés
Melyik PR leírás-rész a legfontosabb, és amit leggyakrabban kihagynak a juniorok?

a) Screenshot
b) Mit változtattál?
c) Miért csináltad? (kontextus, motiváció)
d) Mellékhatások

3. kérdés
Az alábbi leírások közül melyik az ideális egy kis bugfix PR-hoz?

a) fix
b) Closes #88
c) Closes #88 – null check hozzáadva a user.getName() hívás előtt, mert null user esetén NPE-t dobott. Tesztelve: unit teszt + manuális teszt.
d) Részletes 500 szavas magyarázat a teljes kódarchitektúráról

4. kérdés
Mikor kötelező képernyőképet csatolni PR-hoz?

a) Mindig
b) Soha, a kód magáért beszél
c) Ha vizuális / UI változás történt
d) Csak ha a reviewer kér egyet

5. kérdés
Mit jelent a pull_request_template.md fájl a .github/ mappában?

a) A PR review folyamatának automatizálását végzi
b) Automatikusan kitölti a PR leírás mezőjét sablonnal, amikor új PR-t nyitsz
c) A CI/CD pipeline konfigurációját tartalmazza
d) A branch védelmi szabályokat definiálja

6. kérdés
Kollégád azt mondja: „Ez csak egy egysoros változtatás, nem kell PR leírás." Melyik válasz a leghasznosabb?

a) „Igazad van, ne vesztegessük az időt."
b) „Egy mondat kontextus is sokat segít a reviewernek – miért csináltad és mit teszteltél."
c) „Írj legalább 200 szavas leírást minden PR-hoz."
d) „Csak akkor kell leírás, ha a reviewer kéri."

7. kérdés
Mi a különbség a commit üzenet és a PR leírás között?

a) Semmi, ugyanazt a célt szolgálják
b) A commit üzenet az adott commit kontextusát írja le, a PR leírás az egész változtatáscsomag célját és hatását foglalja össze
c) A PR leírás technikai, a commit üzenet kommunikációs
d) A commit üzenet hosszabb, a PR leírás rövidebb szokott lenni

8. kérdés
Egy PR-ban refaktoráltál egy megosztott service osztályt, ami más modulokat is érinthet. Mi a helyes teendő?

a) Nem kell megemlíteni, a reviewer úgyis észreveszi
b) A PR leírás „Mellékhatások" részében jelezd, mi volt az érintett rész és hogyan ellenőrizted
c) Nyiss külön PR-t minden érintett modulhoz
d) Töröld a refaktorálást és hadd maradjon a technikai adósság

9. kérdés (Feladat)
Az alábbi PR leírás mit hiányol? Sorold fel legalább 3 hiányt.

Title: user auth changes
Description: made some changes to authentication

(Nyílt végű feladat – nincs egyetlen helyes válasz, értékeld az általad felsorolt hiányosságokat.)

10. kérdés
Egy PR-t nyitsz, ami frontend változtatást tartalmaz: a bejelentkezési gomb pozícióját megmozdítottad. Mit tegyél mindenképpen?

a) Részletes technikai magyarázatot írni a CSS boxmodelről
b) Csatolni egy előtte/utána screenshotot
c) Kilistázni az összes CSS property-t, amit módosítottál
d) Megvárni, amíg a reviewer kér képernyőképet

Megoldások

  1. b – Aszinkron kommunikáció, kontextus a reviewer számára
  2. c – A motiváció/kontextus a legfontosabb és legtöbbször kihagyott rész
  3. c – Tömör, konkrét, tartalmaz ticket hivatkozást és tesztelési infót
  4. c – UI változásnál kötelező jelleggel érdemes screenshotot csatolni
  5. b – Sablon automatikus betöltése PR nyitáskor
  6. b – Egy mondat is sokat segít, nem kell regény
  7. b – Különböző granularitás és cél
  8. b – Mellékhatások szekció, ellenőrzés dokumentálása
  9. Hiányok: nincs ticket hivatkozás, nincs kontextus (miért kellett változtatni), nincs leírás (mi változott pontosan), nincs tesztelési infó, nincs mellékhatás-jelzés
  10. b – Screenshot vizuális változásnál az egyik leghasznosabb dolog, amit adhatsz
Scroll to Top