GitHub

A félév során a GitHubot használjuk a kód tárolására, a feladatok menedzselésére is és kommunikációra is.

Minden hallgató tagja lesz egy GitHub szervezetnek (Organization), és egy-egy csapatnak (Team A[1-4], Team B[1-4]). Minden csapat külön issue board-dal rendelkezik (Projects), ezen kell vezetni a feladatok (issue) megoldását (részletében lásd Munkafolyamat).

Issue-t nem csak feladatra lehet felvenni, akár kérdésre is (felénk vagy más csapatok felé is), probléma megvitatására is. Ez esetben célszerű megjelölni a type: question címkével. 2017 őszétől csapat (team) szintű fórummal (Discussions) is rendelkezik a GitHub. A szervezeten belül a csapatok hierarchikus struktúrában vannak. A gyökér az Everyone, az összes többi csapat ennek tagja (Group A, Group B csapatokon keresztül). Az Everyone falára írt üzeneteket mindenki megkapja. Ezen keresztül fogunk a félév során kurzus szintű közleményeket kiadni, de bárki használhatja kommunikációra. Ugyanilyen üzenőfallal rendelkezik az összes többi csapat is, amelyre szintén bárki írhat. Ha például a Team2-ből szeretné elérni valaki a Team3-at, akkor mindösszesen annyi a dolga, hogy ír a Team3 üzenőfalára. Az Instructors nevű team-en keresztül az oktatókat lehet elérni ugyanilyen módon.

A comment szekciókban is élnek az @ jeles említések, ez a mi esetünkben @ravaszla és @pintergreg, ugyanígy működik csapatra is pl. @szfmv2020-osz/team-a1, illetve @szfmv2020-osz/instructors a mi esetünkben. Csapat esetében a csapat valamennyi tagja kap értesítést az hivatkozásról.

A GitHub valamennyi elemén használhatóak formázási lehetőségek Markdown stílusban, kód kiemelésre is lehetőség van, amelyet több mint célszerű használni. Ehhez csak a nyelv nevét kell csak a nyitó ``` jelek után írni:

```python
def get_random_number():
    return 4;  # chosen by fair dice roll. guaranteed to be random.
```

Eredmény:

def get_random_number():
    return 4;  # chosen by fair dice roll. guaranteed to be random.

Címkék

Létrehozásra kerültek címkék (Labels) négy „dimenzióban” (vagy kategóriában), amelyek használata elvárás a létrehozott issue-khoz a munka áttekinthetőségének javítása miatt. Kell, hogy legyen az issue-nak típusa, állapota, prioritása és legyen megjelölve a feladat nehézsége is.

Típus (type)

bug
design
documentation
enhancement
integration
question
user story

Állapot (status)

completed
duplicate
help wanted
invalid
pending
review needed

Prioritás (priority)

critical
high
moderate
low

Nehézség (effort)

high
moderate
low

Branching modell

Csoportos munka során fontos tisztázandó kérdés, hogy milyen stratégiával kezeljük a branch-eket. Az egyik legismertebb talán a GitFlow (A successful Git branching model), amelyet mára több kritika is ért.

A legelterjedtebbek tőbb tulajdonságait Scott Shipp War of the Git Flows című cikke nyomán a következő táblázatban foglaltam össze:

	GitFlow	GitHub Flow	OneFlow	GitLab Flow	Trunk-Based Development	Rebasing Flow
Uses feature branches	yes	yes	yes	yes	optionally, if short lived	no
Uses release branches	yes	no	yes	yes	yes	optional
Uses rebasing	no	no	optional	optional	optional	yes
Merges	no fast forward merges	unclear	up to you	up to you	optional	no

A korábbi félévekben a GitFlow szerű megoldást használtuk megbonyolítva azzal, hogy minden csapatnak saját fejlesztői branche-e volt. Ezt jelentősen leegyszerűsítendő a GitHubFlow-ra váltunk.

A master branch védett, nem lehet bele commitolni. Minden feladatohoz tartoznia kell egy issue-nak, és a megoldásához létre kell hozni egy (feature) branchet az aktuális masterről. A feladatot azon kell megoldani, majd PR-et nyitni a masterbe.

Ahhoz, hogy a masterbe kerülhessen a módosítás több követelménynek is teljesülnie kell:

a kód fordul
az összes teszt sikeres
két csapattárs és egy oktató jóvá hagyta (review)
nincs ütközés (conflict)

Fontos: Ha egy Pull Request nem fogadható el, akkor sem kell a PR-t lezárni, lehet tovább dolgozni a forrás branchen, az új commit-okkal automatikusan frissül a PR is addig míg a teszteknek meg nem felel és elfogadásra nem került. Sőt, kifejezetten lehet Draft* Pull Request is létrehozni, jelezve, hogy a munka már tartalmaz véleményezhető elemeket, de még nincs kész.

Ha a PR el lett fogadva be kell zárni azt az issue-t is, amihez a branch kapcsolódott. Tehát ideálisan minden (nem user-story és kérdés) issue-hoz készül(t) egy branch.

Forking

A tárgyhoz nem lesz szükség forkok használatára, de a GitHub workflow szerves részét képezi (különösen nyílt forrású projekteknél) így érdemes lehet ismerni.

Review

review required

Erre az „add your review” szolgál. Fájlonként át lehet nézni minden módosítást, soronként kommentelni, illetve egy globális véleményt írni a PR-ről (+1, -1, -2). A comment opció semleges, nem elfogadás, de nem is elutasítás. A másik két opció elég egyértelmű. Ha változtatást kérsz, akkor addig amíg a PR forrásbranche nem módosul nem lehet újra próbálkozni a PR elfogadásával.

review

Ha minden rendben, akkor el lehet fogadni a PR-et:

Elfogadás után így néz ki:

Társszerzők

A munkafolyamat alapvetően egyéni munkára van kitalálva, de legkevésbé sem tilos a pair programming sem. Volt, hogy Skype-os képernyő-megosztásos módszerrel dolgoztak távolról párban... Ilyenkor mindig felvetődik a kérdés, hogy csak az egyik kolléga nevében történhet a commit de mi van a másikkal... A GitHub-nak van egy funkciója ennek orvoslására. Részletek elérhetőek itt.

Ebben az esetben a commit üzenet törzse után 2 üres sorral elválasztva kell a társszerzőket feltüntetni. Pl.:

Commit message header

Commit message body preceded by an empty line and followed by
two empty lines and the trailer.


Co-authored-by: name <name@example.com>
Co-authored-by: another-name <another-name@example.com>"

Ahhoz, hogy a GitHub a társszerzőt össze is tudja rendelni a felhasználói fiókjával fontos, hogy az a name és különösen az az e-mail szerepeljen, amelyet egyébként git beállításként használ!

E-mail cím védelme

A GH minden felhasználónak biztosít egy "proxy ímélcímet", hogy titokban tarthassa a címét, ez xxxxxxx+username@users.noreply.github.com szerkezetű, ahogy xxxxxxx egy hétjegyű felhasználói azonosító. Bővebben itt. Ezt is lehet használni, nem csak társszerzőhöz hanem saját címnek is, csak legyen konzisztens!

Jegyzet