configlet sync

Übungsdaten mit dem problem-specifications-Repo synchronisieren

Eine Practice-Übung in einem Exercism-Track wird oft anhand einer Spezifikation im Repo exercism/problem-specifications implementiert.

Exercism verlangt bewusst, dass jede Übung ihre eigene Kopie bestimmter Dateien hat (wie .docs/instructions.md), auch wenn diese Übung in problem-specifications existiert. Deshalb hat configlet einen Befehl sync, der prüfen kann, ob solche Practice-Übungen in einem Track mit dieser Upstream-Quelle übereinstimmen, und sie aktualisieren kann, wenn Updates verfügbar sind.

Drei Arten von Daten lassen sich aus problem-specifications aktualisieren: Dokumentation, Metadaten und Tests. Außerdem gibt es eine Art von Daten, die sich aus der track-weiten config.json-Datei befüllen lässt: Dateipfade in den Konfigurationsdateien der Übungen.

Wie diese Datenarten geprüft und aktualisiert werden, beschreiben wir unten in einzelnen Abschnitten. Hier zunächst eine kurze Übersicht:

  • configlet sync arbeitet nur mit Übungen, die in der track-weiten config.json-Datei stehen. Wenn du also eine neue Übung in einem Track implementierst und die ersten Dateien mit configlet sync hinzufügen möchtest, trage die Übung zuerst in die track-weite config.json-Datei ein. Wenn die Übung noch nicht für Nutzer sichtbar sein soll, setze ihren status-Wert auf wip.
  • Ein einfaches configlet sync nimmt keine Änderungen am Track vor und prüft jede Datenart für jede Übung.
  • Um nur einen Teil der Datenarten zu bearbeiten, kombiniere die Optionen --docs, --filepaths, --metadata und --tests.
  • Um die Daten im Track interaktiv zu aktualisieren, verwende die Option --update.
  • Um Dokumentation, Dateipfade und Metadaten im Track ohne Rückfragen zu aktualisieren, verwende --update --yes.
  • Um ohne Rückfragen jeden noch nicht gesehenen Test für eine bestimmte Übung einzubinden, verwende zum Beispiel --update --tests include --exercise prime-factors.
  • Um das Herunterladen des problem-specifications-Repos zu überspringen, füge --offline --prob-specs-dir /path/to/local/problem-specifications hinzu.
  • Beachte, dass configlet sync beim Aktualisieren versucht, die Reihenfolge der Schlüssel in den .meta/config.json-Dateien der Übungen beizubehalten. Um diese Dateien ohne Synchronisierung in eine kanonische Form zu bringen, verwende den Befehl configlet fmt. Allerdings fügt configlet sync fehlende erforderliche Schlüssel (authors, files, blurb) doch hinzu (möglicherweise leer). Das ist zwar weniger „sync-artig“, dafür aber bequemer: Wenn du eine neue Übung implementierst, kannst du sync verwenden, um eine anfängliche .meta/config.json-Datei zu erstellen.
  • configlet sync entfernt Schlüssel, die nicht in der Spezifikation stehen. Eigene Schlüssel-Wert-Paare werden weiterhin unterstützt: Sie müssen in einem JSON-Objekt namens custom stehen.
  • Der Exit-Code ist 0, wenn beim Beenden von configlet alle gesehenen Daten synchronisiert sind, andernfalls 1.

Beachte, dass in den configlet-Versionen 4.0.0-alpha.34 und früher der Befehl sync nur mit Tests arbeitete.

Verwendung

Mit dem Befehl sync kannst du die Dokumentation, Metadaten und Tests von Practice-Übungen aus „problem-specifications“ prüfen oder aktualisieren. Außerdem kann er fehlende files-Werte für Concept- und Practice-Übungen aus der track-weiten „config.json“ prüfen oder befüllen.

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)

Dokumentation

Eine Practice-Übung, die aus dem Repo problem-specifications abgeleitet ist, muss eine .docs/instructions.md-Datei haben (und möglicherweise zusätzlich eine .docs/introduction.md-Datei), die die Übungsdokumentation aus problem-specifications enthält.

Um jede Practice-Übung im Track auf verfügbare Dokumentations-Updates zu prüfen (mit einem Exit-Code ungleich null, wenn mindestens ein Update verfügbar ist):

configlet sync --docs

Um die Dokumentation für jede Practice-Übung interaktiv zu aktualisieren, füge die Option --update hinzu (kurz -u):

configlet sync --docs --update

Um die Dokumentation für jede Practice-Übung ohne Rückfragen zu aktualisieren, füge die Option --yes hinzu (kurz -y):

configlet sync --docs --update --yes

Um nur eine einzelne Practice-Übung zu bearbeiten, verwende die Option --exercise (kurz -e). Um zum Beispiel die Dokumentation für die Übung prime-factors ohne Rückfragen zu aktualisieren:

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

Metadaten

Jede Übung in einem Track muss eine .meta/config.json-Datei haben. Bei einer Practice-Übung, die aus dem Repo problem-specifications abgeleitet ist, sollte diese Datei die Schlüssel-Wert-Paare blurb, source und source_url enthalten, die in der entsprechenden metadata.toml-Datei upstream stehen.

Um jede Practice-Übung auf verfügbare Metadaten-Updates zu prüfen (mit einem Exit-Code ungleich null, wenn mindestens ein Update verfügbar ist):

configlet sync --metadata

Um die Metadaten für jede Practice-Übung interaktiv zu aktualisieren, füge die Option --update hinzu (kurz -u):

configlet sync --metadata --update

Um die Metadaten für jede Practice-Übung ohne Rückfragen zu aktualisieren, füge die Option --yes hinzu (kurz -y):

configlet sync --metadata --update --yes

Um nur eine einzelne Practice-Übung zu bearbeiten, verwende die Option --exercise (kurz -e). Um zum Beispiel die Metadaten für die Übung prime-factors ohne Rückfragen zu aktualisieren:

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

Tests

Wenn ein Track eine Übung implementiert, für die Testdaten im problem-specifications-Repo existieren, muss die Übung eine .meta/tests.toml-Datei enthalten. Ziel der tests.toml-Datei ist es, den Überblick darüber zu behalten, welche Tests von der Übung implementiert werden. Tests in dieser Datei werden über ihre UUID identifiziert, und jeder Test hat einen booleschen Wert, der angibt, ob er von dieser Übung implementiert wird.

Eine tests.toml-Datei hat folgendes Format:

# 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"

In diesem Fall hat der Track beschlossen, zwei der drei verfügbaren Tests zu implementieren. Wenn ein Track einen Testgenerator verwendet, um die Testsuite einer Übung zu erzeugen, muss er den Inhalt der tests.toml-Datei verwenden, um zu bestimmen, welche Tests in die erzeugte Testsuite aufgenommen werden.

Um jede tests.toml-Datei einer Practice-Übung auf verfügbare Test-Updates zu prüfen (mit einem Exit-Code ungleich null, wenn mindestens ein Testfall in den kanonischen Daten der Übung vorkommt, aber nicht in der tests.toml):

configlet sync --tests

Um die tests.toml-Datei für jede Practice-Übung interaktiv zu aktualisieren, füge die Option --update hinzu:

configlet sync --tests --update

Für jeden fehlenden Test wirst du aufgefordert, zu wählen, ob er eingebunden, ausgeschlossen oder übersprungen werden soll, und die entsprechende tests.toml-Datei wird entsprechend aktualisiert. Configlet schreibt die tests.toml-Datei einer Übung, sobald du alle Entscheidungen für diese Übung getroffen hast. Das bedeutet, dass du configlet an einer Eingabeaufforderung beenden kannst (zum Beispiel mit Strg-C im Terminal) und höchstens die Synchronisierungsentscheidungen für eine einzige Übung verlierst.

Um ohne Rückfragen jeden noch nicht gesehenen Testfall einzubinden, verwende --tests include. Um das zum Beispiel für eine Übung namens prime-factors zu tun:

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

Denk daran, diese Tests im Track auch tatsächlich zu implementieren!

Dateipfade

Schließlich kümmert sich der Befehl sync auch um das „Synchronisieren“ aus einer Quelle, die nicht problem-specifications ist, nämlich der track-weiten config.json-Datei. Jede Concept-Übung und jede Practice-Übung muss eine .meta/config.json-Datei mit einem files-Objekt haben, das die (relativen) Speicherorte der Dateien angibt, die die Übung verwendet. Solche Dateipfade folgen meist einem einfachen Muster, sodass configlet die Werte auf Übungsebene aus Mustern im files-Schlüssel der track-weiten config.json-Datei befüllen kann.

Um zu prüfen, ob jede Concept-Übung und jede Practice-Übung im Track einen vollständig befüllten files-Schlüssel hat (oder zumindest einen, der nicht aus dem track-weiten files-Schlüssel befüllt werden kann):

configlet sync --filepaths

(Beachte, dass configlet lint ebenfalls einen Fehler ausgibt, wenn einer Übung der files-Schlüssel fehlt oder leer ist.)

Um leere oder fehlende Werte des files-Schlüssels auf Übungsebene für jede Concept-Übung und jede Practice-Übung aus den Mustern im track-weiten files-Schlüssel zu befüllen:

configlet sync --filepaths --update

Um das ohne Rückfragen und für eine einzelne Übung namens prime-factors zu tun:

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

sync verwenden, wenn du eine neue Übung zu einem Track hinzufügst

Der Befehl sync ist nützlich, wenn du eine neue Übung zu einem Track hinzufügst. Wenn du eine Practice-Übung namens foo hinzufügst, die in problem-specifications existiert, ist ein möglicher Workflow:

  1. Füge manuell einen Eintrag für die Übung foo in die track-weite config.json-Datei ein. Dadurch wird die Übung für configlet sync sichtbar.
  2. Führe configlet sync --docs --filepaths --metadata -uy -e foo aus, um die Dokumentation der Übung und eine anfängliche .meta/config.json-Datei mit befüllten Werten für files, blurb und vielleicht source und source_url zu erstellen.
  3. Bearbeite die .meta/config.json-Datei der Übung nach Belieben. Trage dich zum Beispiel selbst in das authors-Array ein.
  4. Führe configlet sync --tests include -u -e foo aus, um eine .meta/tests.toml-Datei zu erstellen, in der jeder Test eingebunden ist.
  5. Sieh dir die .meta/tests.toml-Datei an und füge include = false bei jedem Testfall hinzu, den die Übung nicht implementieren wird.
  6. Implementiere die Tests für die Übung passend zu denen, die in .meta/tests.toml eingebunden sind.
  7. Füge die anderen erforderlichen Dateien hinzu.