Gyakorlófeladat hozzáadása

Ez a dokumentum elmagyarázza, hogyan adhatsz hozzá új gyakorlófeladatot.

A feladat kiválasztása

A legegyszerűbb módja annak, hogy megnézd, mely gyakorlófeladatok nincsenek még megvalósítva, ha felmész a kurzus build oldalára (pl. https://exercism.org/tracks/csharp/build), és megnézed a „Gyakorlófeladatok” szakaszt.

Caution

A build oldalon lévő adatok naponta egyszer frissülnek.

A feladat vázának létrehozása

Gyorsan létrehozhatod egy új gyakorlófeladat vázát, ha a kurzus gyökérkönyvtárából futtatod a bin/add-practice-exercise szkriptet (forrás):

bin/add-practice-exercise <exercise-slug>

Opcionálisan megadhatod a feladat nehézségét (a -d kapcsolóval) és/vagy a szerző GitHub-felhasználónevét (az -a kapcsolóval) is:

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Ha olyan kurzustárházon dolgozol, amelyben nincs meg ez a fájl, nyugodtan másold be a tárházadba a fenti forráshivatkozás segítségével.

A feladat implementálása

Miután elkészültek a vázfájlok, a következőket kell tenned:

  • Teszteket adsz a tesztfájlhoz
  • Hozzáadsz egy példaimplementációt
  • Meghatározod a stub fájl tartalmát
  • A feladat .meta/config.json fájljában:
    • Hozzáadod a feladat szerzőinek GitHub-felhasználónevét az authors kulcshoz
  • A kurzus config.json fájljában:
    • Ellenőrzöd és frissíted a feladat nehézségét
    • Fogalmakat adsz a practices kulcshoz (csak akkor szükséges, ha a kurzusnak vannak tanulófeladatai)
    • Fogalmakat adsz a prerequisites kulcshoz (csak akkor szükséges, ha a kurzusnak vannak tanulófeladatai)

Tesztek hozzáadása

A feladat hozzáadásának egyik legfontosabb része a tesztek megírása. Nagyjából két lehetőség van, amikor egy gyakorlófeladathoz teszteket írsz:

  1. A teszteket a nulláról írod meg, a feladat canonical-data.json fájljában lévő teszteseteket használva, amelyek a problem-specifications repóban találhatók.
  2. Átülteted a teszteket egy másik kurzus implementációjából (tipp: menj a https://exercism.org/exercises/<slug> címre, hogy áttekintést kapj arról, mely kurzusok valósítottak meg egy adott feladatot).

A második lehetőség különösen vonzó lehet, mert gyorsan eredményt adhat. Tartsd azonban észben, hogy az implementációt hozzá kell igazítanod a kurzusodhoz. Például van, amelyik kurzus nem használ osztályokat, csak függvényekkel dolgozik. Ha viszont a kurzusod jellemzően objektumokkal dolgozik, akkor az implementációt ahhoz igazítsd, ami a legjobban illik a kurzusodhoz.

Note

Egyes kurzusok tesztgenerátort használnak a feladat tesztfájljainak automatikus (újra)generálására. Nézd meg a kurzus dokumentációját, hogy van-e tesztgenerátor, és ha igen, hogyan kell használni.

Példaimplementáció hozzáadása

Ahhoz, hogy biztos legyen, írható olyan kód, amely átmegy a teszteken, hozzá kell adnod egy példaimplementációt.

Note

A kódnak nem kell idiomatikusnak lennie, csak át kell mennie a teszteken.

Ellenőrizheted, hogy a példaimplementáció átmegy-e az összes teszten, ha a kurzus gyökérkönyvtárából futtatod a bin/verify-exercises szkriptet (forrás):

bin/verify-exercises <exercise-slug>

A kimenet alapján ellenőrizd, hogy a példaimplementáció átmegy az összes teszten.

Note

Ha olyan kurzustárházon dolgozol, amelyben nincs meg ez a fájl, nyugodtan másold be a tárházadba a fenti forráshivatkozás segítségével.

Advanced

A színfalak mögött a bin/verify-exercises szkript több dolgot is csinál:

  • A feladatot egy ideiglenes könyvtárba másolja
  • Felülírja a stub fájl(oka)t a példaimplementációs fájllal/-okkal
  • Ha a tesztfájlban vannak kihagyott tesztek, azokat »kihagyatlanná« teszi
  • Lefuttatja a teszteket

Stub fájl(ok) hozzáadása

A stub implementációs fájl(ok) kiindulópontot adnak a tanulóknak.

Azt javasoljuk, hogy a stub fájlok a lehető legkevesebb kódot tartalmazzák, hogy:

  • a tanuló azonnal elkezdhesse megvalósítani a tesztek átmenéséhez szükséges logikát
  • a tanuló ne szembesüljön „furcsa” szintaktikai hibákkal

A gyakorlatban ez azt jelenti, hogy definiálod azokat a függvényeket/metódusokat, amelyeket a teszthalmaz tesztel. A kurzusok szabadon dönthetik el, hogyan állítják össze ezt a kódot, amíg biztosítják, hogy a stub kód kezdetben minden teszten elbukik.

Példák

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

A feladat lintelése

Az utolsó lépés, hogy futtatod a lintert, amely ellenőrzi, hogy a kurzus (konfigurációs) fájljai megfelelően strukturáltak-e, szintaktikailag és szemantikailag is.

Először győződj meg róla, hogy a configlet legújabb verziójával rendelkezel, ehhez futtasd:

bin/fetch-configlet

Ezután futtasd a lintert:

bin/configlet lint

A kimenet alapján ellenőrizd, hogy minden rendben van.

Pull request beküldése

Miután minden rendben van, beküldhetsz egy pull requestet a kurzus repójába.

Beküldés előtt olvasd el a közreműködői pull request útmutatót és a pull request útmutatót.

Ügyelj rá, hogy a PR leírása felsorolja a hozzáadott feladatot.