configlet sync

Feladatadatok szinkronizálása a problem-specifications repóval

Egy gyakorlófeladatot az Exercism egy kurzusán gyakran egy specifikáció alapján valósítanak meg az exercism/problem-specifications repóból.

Az Exercism szándékosan megköveteli, hogy minden feladat saját másolattal rendelkezzen bizonyos fájlokból (például a .docs/instructions.md fájlból), még akkor is, ha a feladat létezik a problem-specifications repóban. Ezért a configlet rendelkezik egy sync paranccsal, amely ellenőrizheti, hogy az ilyen gyakorlófeladatok egy kurzuson szinkronban vannak-e ezzel a forrásrepóval, és frissítheti is őket, amikor frissítések érhetők el.

Háromféle adat frissíthető a problem-specifications repóból: a dokumentáció, a metaadatok és a tesztek. Ezen kívül egyféle adat tölthető fel a kurzusszintű config.json fájlból: a feladatok konfigurációs fájljaiban szereplő fájlútvonalak.

Ezeknek az adatfajtáknak az ellenőrzését és frissítését az alábbi külön szakaszokban írjuk le, de gyors összefoglalóként:

  • A configlet sync csak azokkal a feladatokkal foglalkozik, amelyek szerepelnek a kurzusszintű config.json fájlban. Ezért ha új feladatot valósítasz meg egy kurzuson, és a kezdő fájlokat a configlet sync segítségével szeretnéd hozzáadni, először vedd fel a feladatot a kurzusszintű config.json fájlba. Ha a feladat még nem kész arra, hogy a felhasználók lássák, állítsd a status értékét wip-re.
  • Egy sima configlet sync nem módosít semmit a kurzuson, és minden adatfajtát ellenőriz minden feladatnál.
  • Ha csak az adatfajták egy részével szeretnél dolgozni, használd a --docs, --filepaths, --metadata és --tests kapcsolók valamilyen kombinációját.
  • Ha interaktívan szeretnéd frissíteni az adatokat a kurzuson, használd az --update kapcsolót.
  • Ha nem interaktívan szeretnéd frissíteni a dokumentációt, a fájlútvonalakat és a metaadatokat a kurzuson, használd a --update --yes kapcsolókat.
  • Ha egy adott feladat összes még nem látott tesztjét nem interaktívan szeretnéd felvenni, használd például a --update --tests include --exercise prime-factors kapcsolókat.
  • Ha ki szeretnéd hagyni a problem-specifications repo letöltését, add hozzá a --offline --prob-specs-dir /path/to/local/problem-specifications kapcsolókat.
  • Vedd figyelembe, hogy a configlet sync frissítéskor igyekszik megtartani a kulcsok sorrendjét a feladatok .meta/config.json fájljaiban. Ha ezeket a fájlokat szinkronizálás nélkül, kanonikus formában szeretnéd megírni, használd a configlet fmt parancsot. A configlet sync viszont igenis hozzáadja a (esetleg üres) kötelező kulcsokat (authors, files, blurb), amikor azok hiányoznak. Ez kevésbé „szinkronszerű”, de kényelmesebb: új feladat megvalósításakor a sync segítségével létrehozhatsz egy kezdő .meta/config.json fájlt.
  • A configlet sync eltávolítja azokat a kulcsokat, amelyek nincsenek benne a specifikációban. Az egyéni kulcs/érték párok továbbra is támogatottak: azokat egy custom nevű JSON-objektumba kell írni.
  • A kilépési kód 0, ha a configlet kilépésekor az összes látott adat szinkronban van, egyébként 1.

Vedd figyelembe, hogy a configlet 4.0.0-alpha.34 és korábbi kiadásaiban a sync parancs csak a tesztekkel foglalkozott.

Használat

A sync parancs használható a gyakorlófeladatok dokumentációjának, metaadatainak és tesztjeinek ellenőrzésére vagy frissítésére a problem-specifications repóból. Ellenőrizheti vagy kitöltheti a hiányzó files értékeket is a tanulófeladatok és gyakorlófeladatok számára a kurzusszintű config.json fájlból.

configlet [global-options] sync [command-options]

Global options:
  -h, --help                   Show this help message and exit
      --version                Show this tool's version information and exit
  -t, --track-dir <dir>        Specify a track directory to use instead of the current directory
  -v, --verbosity <verbosity>  The verbosity of output. Allowed values: q[uiet], n[ormal], d[etailed]

Options for sync:
  -e, --exercise <slug>        Only operate on this exercise
  -p, --prob-specs-dir <dir>   Use this 'problem-specifications' directory, rather than cloning temporarily
  -o, --offline                Do not check that the directory specified by --prob-specs-dir is up to date
  -u, --update                 Prompt to update the seen data that are unsynced
  -y, --yes                    Auto-confirm prompts from --update for updating docs, filepaths, and metadata
      --docs                   Sync Practice Exercise '.docs/introduction.md' and '.docs/instructions.md' files
      --filepaths              Populate empty 'files' values in Concept/Practice exercise '.meta/config.json' files
      --metadata               Sync Practice Exercise '.meta/config.json' metadata values
      --tests [mode]           Sync Practice Exercise '.meta/tests.toml' files.
                               The mode value specifies how missing tests are handled when using --update.
                               Allowed values: c[hoose], i[nclude], e[xclude] (default: choose)

Dokumentáció

Egy problem-specifications repóból származó gyakorlófeladatnak rendelkeznie kell egy .docs/instructions.md fájllal (és esetleg egy .docs/introduction.md fájllal is), amely tartalmazza a feladat dokumentációját a problem-specifications repóból.

Ha ellenőrizni szeretnéd, hogy van-e elérhető dokumentációfrissítés a kurzus minden gyakorlófeladatához (nullától eltérő kilépési kóddal lép ki, ha legalább egy frissítés elérhető):

configlet sync --docs

Ha interaktívan szeretnéd frissíteni a dokumentációt minden gyakorlófeladatnál, add hozzá a --update kapcsolót (vagy röviden a -u-t):

configlet sync --docs --update

Ha nem interaktívan szeretnéd frissíteni a dokumentációt minden gyakorlófeladatnál, add hozzá a --yes kapcsolót (vagy röviden a -y-t):

configlet sync --docs --update --yes

Ha egyetlen gyakorlófeladattal szeretnél dolgozni, használd a --exercise kapcsolót (vagy röviden a -e-t). Például hogy nem interaktívan frissítsd a prime-factors feladat dokumentációját:

configlet sync --docs -uy -e prime-factors

Metaadatok

A kurzus minden feladatához tartoznia kell egy .meta/config.json fájlnak. Egy problem-specifications repóból származó gyakorlófeladat esetében ennek a fájlnak tartalmaznia kell a blurb, source és source_url kulcs/érték párokat, amelyek a megfelelő upstream metadata.toml fájlban szerepelnek.

Ha ellenőrizni szeretnéd, hogy van-e elérhető metaadatfrissítés minden gyakorlófeladatnál (nullától eltérő kilépési kóddal lép ki, ha legalább egy frissítés elérhető):

configlet sync --metadata

Ha interaktívan szeretnéd frissíteni a metaadatokat minden gyakorlófeladatnál, add hozzá a --update kapcsolót (vagy röviden a -u-t):

configlet sync --metadata --update

Ha nem interaktívan szeretnéd frissíteni a metaadatokat minden gyakorlófeladatnál, add hozzá a --yes kapcsolót (vagy röviden a -y-t):

configlet sync --metadata --update --yes

Ha egyetlen gyakorlófeladattal szeretnél dolgozni, használd a --exercise kapcsolót (vagy röviden a -e-t). Például hogy nem interaktívan frissítsd a prime-factors feladat metaadatait:

configlet sync --metadata -uy -e prime-factors

Tesztek

Ha egy kurzus olyan feladatot valósít meg, amelyhez tesztadatok léteznek a problem-specifications repóban, a feladatnak tartalmaznia kell egy .meta/tests.toml fájlt. A tests.toml fájl célja, hogy nyilvántartsa, mely teszteket valósítja meg a feladat. A fájlban a teszteket az UUID-juk azonosítja, és minden teszthez tartozik egy logikai érték, amely jelzi, hogy a feladat megvalósítja-e azt.

A tests.toml fájl formátuma a következő:

# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.
[1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
description = "basic"
[79ae3889-a5c0-4b01-baf0-232d31180c08]
description = "lowercase words"
[ec7000a7-3931-4a17-890e-33ca2073a548]
description = "invalid input"
include = false
comment = "excluded because we don't want to add error handling to the exercise"

Ebben az esetben a kurzus úgy döntött, hogy a három elérhető teszt közül kettőt valósít meg. Ha egy kurzus tesztgenerátort használ egy feladat tesztcsomagjának előállítására, akkor a tests.toml fájl tartalmát kell használnia annak meghatározásához, hogy mely teszteket vegye fel az előállított tesztcsomagba.

Ha ellenőrizni szeretnéd, hogy minden gyakorlófeladat tests.toml fájljához van-e elérhető tesztfrissítés (nullától eltérő kilépési kóddal lép ki, ha legalább egy olyan teszteset szerepel a feladat kanonikus adataiban, amely nincs benne a tests.toml-ban):

configlet sync --tests

Ha interaktívan szeretnéd frissíteni minden gyakorlófeladat tests.toml fájlját, add hozzá a --update kapcsolót:

configlet sync --tests --update

Minden hiányzó tesztnél ez arra kéri a felhasználót, hogy válassza ki, felveszi-e, kizárja-e vagy kihagyja-e, és ennek megfelelően frissíti a hozzá tartozó tests.toml fájlt. A configlet akkor írja ki a feladat tests.toml fájlját, amikor a felhasználó befejezte a választást az adott feladatnál. Ez azt jelenti, hogy a configlet egy felszólításnál megszakítható (például a Ctrl-C lenyomásával a terminálban), és legfeljebb egy feladat szinkronizálási döntéseit veszíted el.

Ha nem interaktívan szeretnéd felvenni az összes még nem látott tesztesetet, használd a --tests include kapcsolót. Például hogy ezt egy prime-factors nevű feladatnál tedd:

configlet sync --tests include -u -e prime-factors

Ne feledd, hogy ezeket a teszteket ténylegesen meg is kell valósítani a kurzuson!

Fájlútvonalak

Végül a sync parancs egy olyan forrásból is elvégzi a „szinkronizálást”, amely nem a problem-specifications repó, hanem a kurzusszintű config.json fájl. Minden tanulófeladatnak és gyakorlófeladatnak rendelkeznie kell egy .meta/config.json fájllal, amelyben egy files objektum adja meg a feladat által használt fájlok (relatív) helyét. Az ilyen fájlútvonalak általában egyszerű mintát követnek, így a configlet ki tudja tölteni a feladatszintű értékeket a kurzusszintű config.json fájl files kulcsában szereplő minták alapján.

Ha ellenőrizni szeretnéd, hogy a kurzus minden tanulófeladatának és gyakorlófeladatának teljesen kitöltött files kulcsa van-e (vagy legalább olyan, amely nem tölthető ki a kurzusszintű files kulcsból):

configlet sync --filepaths

(Vedd figyelembe, hogy a configlet lint szintén hibát jelez, ha egy feladatnál hiányzik vagy üres a files kulcs.)

Ha minden tanulófeladat és gyakorlófeladat feladatszintű files kulcsának üres vagy hiányzó értékeit ki szeretnéd tölteni a kurzusszintű files kulcs mintái alapján:

configlet sync --filepaths --update

Ha ezt nem interaktívan és egyetlen prime-factors nevű feladatnál szeretnéd megtenni:

configlet sync --filepaths -uy -e prime-factors

A sync használata, amikor új feladatot adsz egy kurzushoz

A sync parancs hasznos, amikor új feladatot adsz egy kurzushoz. Ha egy foo nevű gyakorlófeladatot adsz hozzá, amely létezik a problem-specifications repóban, az egyik lehetséges munkafolyamat a következő:

  1. Kézzel adj hozzá egy bejegyzést a kurzusszintű config.json fájlhoz a foo feladathoz. Ettől a feladat láthatóvá válik a configlet sync számára.
  2. Futtasd a configlet sync --docs --filepaths --metadata -uy -e foo parancsot a feladat dokumentációjának és egy kezdő .meta/config.json fájlnak a létrehozásához, kitöltött files, blurb, valamint esetleg source és source_url értékekkel.
  3. Szerkeszd a feladat .meta/config.json fájlját tetszés szerint. Például vedd fel magadat az authors tömbbe.
  4. Futtasd a configlet sync --tests include -u -e foo parancsot egy .meta/tests.toml fájl létrehozásához, amelyben minden teszt szerepel.
  5. Nézd át azt a .meta/tests.toml fájlt, és adj hozzá include = false sort minden olyan tesztesethez, amelyet a feladat nem fog megvalósítani.
  6. Valósítsd meg a feladat tesztjeit úgy, hogy megfeleljenek a .meta/tests.toml fájlban szereplőknek.
  7. Add hozzá a többi szükséges fájlt.