Figyelem: A gyakorlatok során törekedjen mindenki arra, hogy professzionális jellegű munkát végezzen! Például kerüljük az asdfg commit megjegyzéseket, nem sokkal több idő azt írni helyette, hogy Add acceleration feature vagy Fix #5 (további tanácsokat commit megjegyzések írásához lásd itt vagy itt).

Környezet kialakítása

Fejlesztéshez szükséges eszközök

A gyakorlatok során sokszor IDE helyett parancssori eszközöket fogunk javasolni, mert egyrészt egy CI környezetben azokat lehet csak használni, másrészt ilyen bevezető jellegű feladatoknál többet lehet belőle tanulni.

A gyakorlat elvégzéséhez az alábbi szoftverekre van szükség (ezek elérhetők a BME cloud-ban lévő sablonon vagy telepíthetők saját gépre is):

• Java JDK 11 vagy újabb
• Git parancssori kliens
• Apache Maven 3.6.0 vagy újabb
• Egyszerű IDE-nek a Visual Studio Code-ot javasoljuk
  • Extensions: Extension Pack for Java, Sonarlint

Figyelem: Saját környezetet használata előtt a Java JDK beállítását ellenőrizzük: JDK legyen és ne JRE, PATH és JAVA_HOME helyesen beállítva (részletesen lásd például itt).

java -version
javac -version

Tárhely létrehozása

Mivel most mindenki egymástól függetlenül fogja elvégezni ugyanazokat a kiegészítéseket és javításokat ugyanazon a nyílt forráskódú projekten, ezért a bevett módszer (fork) helyett mindenki saját magának készít egy tárhelyet (repository) azonos tartalommal, amin tud dolgozni.

1. [local] Indítsa el a tantárgy weboldalán javasolt virtuális gépet és tekintse át a labor elvégzéséhez szükséges eszközöket.
2. [web] A saját GitHub felhasználója alá készítsen egy ivt-lab nevű publikus tárhelyet és állítsa is inicializált állapotba (Initialize this repository with a README). Ezen a tárhelyen kell majd végig dolgozni a labor folyamán.

Token létrehozása

Figyelem: A GitHub felületéhez 2021 óta nem lehet jelszóval csatlakozni parancssorból. A bejelentkezéshez egy úgynevezett personal access tokent (PAT) kell készíteni, amivel be lehet jelentkezni a parancssorból.

1. A GitHub felületén kattintson a saját profiljára, majd válassza a Settings menüpontot.
2. A bal oldalsó sáv alján válassza a <> Developer settings menüpontot.
3. A bal oldalsó sávban válassza a Personal access token majd a Tokens (classic) menüpontot.
4. Kattintson a Generate a personal access token gombra.
5. Adjon a tokennek egy nevet, állítsa be a lejáratát tetszőleges időre, célszerűen a labor, vagy a félév végére.
6. A Select scopes alatt pipálja be a repo checkboxot.
7. Végül kattintson a Generate token gombra.
8. Az elkészült tokent a git push művelet során a jelszó helyett kell használni.

Tárhely feltöltése

1. [web] Olvassa el a közös projekt README leírását, hogy megismerje az alkalmazást, amivel dolgozni kell.
2. [local] Klónozza le helyileg a saját tárhelyét a virtuális gépre (git clone parancs).
   • Figyelem: nem kell a helyi tárhelyet előtte inicializálni (git init)!
   • Figyelem: a klónozás után be kell lépni az ivt-lab könyvtárba (cd)!
3. [web/local] Töltse le ZIP-ként a közös projekt tartalmát, és másolja bele fájlszinten a saját lokális tárhelyébe a ZIP-ben lévő ivt-lab-master könyvtár tartalmát (maga a könyvtár nem kell!).
4. [local] Nézze meg, hogy milyen fájlok nincsenek jelenleg még verziókezelés alatt (git status), adjon minden új vagy módosított fájlt hozzá az aktuális indexhez (git add), véglegesítse azokat (git commit), majd küldje át az új tartalmat a GitHub-on lévő tárhely példánynak (git push).
   • A git commit parancs első végrehajtásakor hiányolhatja a felhasználó és az e-mail cím konfigurációját, ezeket a git config user.email "you@example.com" és git config user.name "Your Name" parancsokkal lehet megtenni.
5. [web] Ellenőrizze a GitHub tárhelyén, hogy a fájlok sikeresen megjelentek-e!

CI feladatok (GitHub Actions)

A saját Git tárolónkban lévő projekt fordítását és tesztelését végezzük el a GitHub Actions segítségével.

1. [web] Nyissa meg a projektet a saját GitHub tárhelyén.
2. [web] Kattintson az Actions gombra.
3. [web] A felajánlott lehetőségekből válassza a 'Java with Maven' munkafolyamatot (workflow). Ezzel megjelenik egy felület, ahol a minta alapján létrehozott maven.yml fájlt lehet szerkeszteni.
4. [web] Ellenőrizze a yml (YAML) fájlt, hogy JDK 11-et használ-e a fordítás során! A szintaxissal kapcsolatos segítséget a hivatkozott oldalon talál.
5. [web] Ha végzett, akkor a 'Start commit' gombbal véglegesítse a fájlt. Ezzel elvileg elindul egy példány a létrehozott Actions munkafolyamatból. Kövesse nyomon a munkafolyamat lefutását az Actions oldalon.
6. [web] Értelmezze az Actions felületén a fordítás eredményét (a commit nevére kattintva érhetők el a részletes naplófájlok, keresse meg a build feladaton belül a 'Build with Maven' lépést). Amennyiben megfelelően végezte el az előbbi feladatokat a projektnek le kell fordulnia, ugyanakkor az egyik egységtesztnek hibát kell jeleznie (lásd következő feladat).

GitHub Flow feladatok

A GitHub Actions által felfedett egységteszt hiba abból fakad, hogy egy funkció még nincs teljesen implementálva a kódban (torpedó ALL tüzelési módja). Ennek kijavítását egy GitHub Flow munkafolyamat mentén végezze el.

1. [web/local] Az Actions kimenete és a forráskód vizsgálata alapján határozza meg a teszt hibájának az okát.

2. [web] Definiálja pontosan az új funkciót, az elvégzendő implementációs feladatot és ehhez hozzon létre egy hibajegyet (Issue) a GitHub webes felületén.

3. [web] Hozzon létre egy fejlesztési ágat (branch) ezen implementációs feladatok elvégzéséhez.

4. [local] Töltse le a távoli tárolót (pull) és váltson a megfelelő ágra (checkout).

5. [local] Végezze el az implementációt és tesztelje azt egy helyi futtatás keretében (mvn test).

6. [local] Véglegesítse és töltse fel (commit and push) a változásokat a távoli tárolóba.

7. [web] Az így kapott változások alapján hozzon létre egy pull request-et a webes felületen, hogy megvitatható legyen a módosítás a fejlesztőcsapaton belül. A pull request szövegébe írjuk bele, hogy "Fix #1", ezzel jelezve, hogy az 1-es hibajegyet fogja majd lezárni.

   Figyelem: Még ha helyesen implementálta is a hiányzó funkciót, és a helyi gépen működik is a teszt, ezen a ponton a létrehozott CI pipeline hibára fog futni. Ha a hiba az hogy: "Resource not accessible by integration", akkor kövesse ezt a leírást.

8. [web] Vizsgálja meg a létrehozott pull request-et, és ha rendben találja, akkor fogadja el, olvassza vissza a master ágba és törölje ki a fejlesztésre használt ágat. (A pull request nyújtotta átvizsgálási lehetőségekkel a következő gyakorlaton foglalkozunk majd.)

9. [local] Töltse le a távoli tárolóból a változásokat és vizsgálja meg őket a git log utasítás segítségével.

További információ:

• Mastering Issues
• Understanding the GitHub flow

Konfliktus előállítása összeolvasztás esetén (Merge conflict)

1. [local] Hozzon létre parancssori eszközökkel két új ágat. (branch-A, branch-B).
2. [local] Váltson át a branch-A-ra, szerkessze egy adott fájl adott sorát, majd véglegesítse a változásokat (commit).
3. [local] Váltson át a branch-B-re, szerkessze ugyanazon fájl ugyanazon sorát kicsit máshogy, majd véglegesítse a változásokat (commit).
4. [local] Váltson vissza a master ágra és olvassza (merge) bele előbb az egyik, majd a másik branch-et. Ellenőrizze az összeolvasztás művelet eredményét, oldja fel a keletkezett konfliktust és véglegesítse a feloldás során tett módosításokat.

CI build kiegészítése (opcionális)

Most, hogy sikeresen lefut a build a GitHub Actions CI szerveren is, érdemes még néhány dolgot beállítani.

1. A Maven kimenet a CI szerver logjában nehezen olvasható a sok függőség letöltés üzenet miatt. Adjuk hozzá a mvn parancshoz a --no-transfer-progress kapcsolót. Olvashatóbb lett a log?
2. Ellenőrizzük/állítsuk be a Maven termékek (pl. a letöltött függőségek) gyorsítótárazását (cache): leírás (vagy másik megoldás).

A gyakorlat befejezése

Véglegesítsen minden változást, töltse fel a távoli tárolóba és ellenőrizze, hogy a GitHub Actions fordítás is helyesen lefut-e.

Figyelem: A saját GitHub tárhelyet ne törölje, a további gyakorlatokon is azon fog dolgozni.