Karbantartóként viszonylag rendszeresen fogsz pull requesteket átnézni.
Ez a dokumentum néhány Exercism-specifikus irányelvet tartalmaz a pull requestek átnézéséhez.
Feladatok pull requestjeinek átnézése
Egy tanuló- vagy gyakorlófeladat pull requestjének átnézése ijesztő lehet a feladattípusok körüli rengeteg szabály miatt.
Ezért egy karbantartó első körös átnézése gyakran két-három órát vesz igénybe, és több tucat hozzászólást eredményez.
A tanulófeladatoknál emellett vannak hasonló célú és tartalmú fájlok is (például a feladat és a fogalom bevezetője), ahol elengedhetetlen, hogy először az egyiket tegyük tökéletessé, mielőtt túl messzire kalandoznánk.
Hogy ez a folyamat gördülékenyebb legyen, az alábbi javaslatokat dolgoztuk ki.
Javaslat: egyetlen tapasztalt karbantartó vigye az első körös átnézést
Az alábbi okok szólnak amellett, hogy pontosan egy tapasztalt karbantartó vigye az első körös átnézést:
- Nem végezzük el kétszer ugyanazt az átnézést
- A közreműködő és a karbantartó párban dolgozik a pull requesten, ami remélhetőleg azt az érzést adja a közreműködőnek, hogy nincs egyedül
- Nem érkeznek egymásnak ellentmondó hozzászólások más karbantartóktól
Javaslat: mergelés wip állapottal
Amint a közreműködő és a karbantartó is elégedett a feladattal, a feladatot úgy kell mergelni, hogy a status mezője wip (folyamatban lévő munka) legyen.
Az ilyen állapotú feladatok nem érhetők el a tanulók számára, de a legjobb mentoraink megtekinthetik majd őket (amint ezt valamikor a jövőben megvalósítjuk).
Ezek a nagy reputációjú felhasználók aztán kipróbálhatják a feladatot, és issue-kat vagy pull requesteket nyithatnak a javítása vagy fejlesztése érdekében.
Ennek a megközelítésnek a fő előnyei:
- Leveszi az eredeti közreműködő-karbantartó páros válláról azt a terhet, hogy mindennek tökéletesnek kell lennie
- Nem vezet óriási, sok szereplős pull requestkörökhöz (amelyeket nagyon nehéz kézben tartani)
Gyakorlófeladatok pull requestjeinek átnézése
Javaslat: gondold meg, hogy a változás egyáltalán a problems-specifications repóba való-e
A gyakorlófeladatok egyes tartalmai (például a bevezetőjük) a (közös) metaadataikból származnak, ahogy azokat a problems-specifications repo meghatározza.
Amikor egy ilyen tartalmat módosító pull requestet nézel át, gondold meg, hogy a változás más kurzusoknak is hasznára válhat-e.
Ha igen, javasold a közreműködőnek, hogy nyisson pull requestet a problems-specifications repo megfelelő fájljához
Általános átnézési javaslatok
Javaslat: egy elsődleges átnéző pull requestenként
Minden pull requesthez egy elsődleges átnéző tartozzon (amelyik karbantartó magára vállalja).
A többi karbantartó és/vagy közösségi tag másodlagos szerepben vegyen részt.
Két fő módja van annak, hogy egy másodlagos szerepben lévő ember hozzájáruljon az átnézéshez:
- Korrektúrázd a helyesírást és a nyelvtant, de csak azután, hogy az elsődleges átnéző végzett az első körrel.
Frusztráló lehet a közreműködőknek, ha kapnak egy helyesírási és nyelvtani átnézést, kijavítják, majd megjelenik egy karbantartó, és mélyrehatóbb változtatásokat kér tőlük.
Vagyis: a korrektúrát azután végzed el, hogy a lényegesebb változásokat rendeztétek (vagy esetleg egy külön pull requestben).
- Rámutatsz dolgokra nem cselekvésre felszólító módon, az átnézőnek.
Ha olyan dolgokhoz szólsz hozzá, amelyeken az elsődleges átnézőnek érdemes elgondolkodnia, vagy amelyeket esetleg kihagyott, a hozzászólásodat véleményként vagy kérdés formájában fogalmazd meg.
Ez világossá teszi a közreműködő számára, hogy nem kérsz tőle változtatásokat, ami kevésbé zavarja majd őt.
Csökkenti annak az esélyét is, hogy az elsődleges átnéző úgy érezze, „aláássák a tekintélyét”.
Javaslat: ne szólj hozzá a témába nem vágó dolgokhoz
Amikor egy pull requestet nézel át, kizárólag az ahhoz közvetlenül kapcsolódó dolgokhoz szólj hozzá.
Minden máshoz nyiss egy issue-t, vagy hozz létre egy külön (utólagos) pull requestet.
Javaslat: hivatkozz dokumentációra
Amikor csak lehet, mindig próbálj olyan dokumentációra hivatkozni, amely megmagyarázza, miért szólsz hozzá valamihez.
Ez nagyban csökkenti annak esélyét, hogy a dolog vitává fajuljon.
Javaslat: kérj segítséget más csapatoktól
Ha segítséget szeretnél kérni egy pull request átnézéséhez, két konkrét csapatot is meg tudsz jelölni:
-
@exercism/reviewers: általános átnézésekhez
-
@exercism/github-actions: a GitHub actions kapcsán felmerülő kérdésekhez
