Die erste Übung hinzufügen

Die erste Übung jedes Tracks ist eine ganz einfache „Hello, World!“-Übung.

Sinn dieser Übung ist es, schnell sicherzustellen, dass alles richtig zusammenspielt. Sie bestätigt, dass der Nutzer die Programmierumgebung korrekt installiert hat, dass er weiß, wie man die Tests ausführt, und dass er sie zum Laufen bringen kann. Darüber hinaus stellt sie beim Kommandozeilen-Client (CLI) von Exercism sicher, dass dieser korrekt installiert und konfiguriert ist, und dass die Website die richtigen Dateien für die Übung ausliefert, ohne unnötige Artefakte mitzugeben. Und schließlich sorgt sie dafür, dass der Nutzer mit dem Ablauf vertraut ist: eine Übung mit der CLI herunterladen, ein Problem in der lokalen Entwicklungsumgebung lösen und die Lösung wieder auf der Website einreichen.

Mit anderen Worten: Hier geht es noch nicht wirklich darum, etwas über die Sprache selbst zu lernen. Wir wollen etwas ganz Einfaches.

Das ist wahrscheinlich auch der schwierigste Teil beim korrekten Einrichten des Track-Repositories, denn an einer Übung hängen viele bewegliche Teile.

Die Übung umsetzen

Für die „Hello, World!“-Übung gelten ein paar besondere Regeln:

  • Sie ist immer die erste Übung in einem Track
  • Jeder Track muss sie umsetzen
  • Die Testdatei enthält nur einen Test
  • Die Stub-Datei enthält eine fast funktionierende Implementierung, aber statt „Hello, World!“ verwendet sie „Goodbye, Mars!“
  • Sie hat keine prerequisites
  • Sie hat keine practices

Dateipfade festlegen

Die „Hello, World!“-Übung (und tatsächlich alle Übungen auf Exercism) benötigt einen bestimmten Satz von Dateien:

  • Dokumentation: erklärt den Lernenden, was sie tun müssen (kann automatisch generiert werden).
  • Metadaten: liefern Exercism einige Informationen über die Übung (können größtenteils automatisch generiert werden).
  • Testsuite: überprüft die Korrektheit einer Lösung (Track-spezifisch).
  • Stub-Implementierung: bietet den Lernenden einen Ausgangspunkt (Track-spezifisch).
  • Beispielimplementierung: liefert eine Beispielimplementierung, die alle Tests besteht (Track-spezifisch).
  • Zusätzliche Dateien: stellen sicher, dass die Tests ausgeführt werden können (Track-spezifisch, optional).

Bevor wir die „Hello, World!“-Übung erstellen können, musst du ein paar Entscheidungen über die Track-spezifischen Dateinamen und Dateipfade treffen (Testsuite, Stub-Implementierung, Beispielimplementierung und alle zusätzlichen Dateien).

Als Faustregel gilt: Verwende Namen, die für die Sprache idiomatisch sind. Wo es keine starken Vorlieben gibt, sind flachere Verzeichnisstrukturen besser. Die Beispielimplementierung muss vom CI-Skript erkannt werden können, deshalb ist es ratsam, einen generischen Basisnamen zu wählen, den alle Übungen verwenden können, z. B. example, sample oder reference-solution.

Dateipfade konfigurieren

Nachdem du die Track-spezifischen Dateipfade gewählt hast, solltest du sie im Schlüssel files in der config.json-Datei im Stammverzeichnis konfigurieren. Der Schlüssel files dient als Vorlage für alle Übungen. So weiß jedes Tool (einige davon nutzen wir gleich), wo es nach Dateien suchen muss. Mit verschiedenen Platzhaltern kannst du den Slug der Übung (in diesem Fall hello-world) bequem konfigurieren.

Beispiel

Wenn dein Track PascalCase für seine Dateien verwendet, könnte der Schlüssel files so aussehen:

"files": {
  "solution": [
    "%{pascal_slug}.cs"
  ],
  "test": [
    "%{pascal_slug}Tests.cs"
  ],
  "example": [
    ".meta/Example.cs"
  ]
}
Note

Die Beispieldatei(en) sollten im Verzeichnis .meta liegen.

Weitere Informationen findest du in der Dokumentation zum Schlüssel files.

Dateien erstellen

Nachdem du die Vorlagen für die Dateipfade festgelegt hast, kannst du die Dateien für die „Hello, World!“-Übung schnell anlegen, indem du im Stammverzeichnis des Tracks die folgenden Befehle ausführst:

bin/fetch-configlet
bin/configlet create --practice-exercise hello-world

Autor festlegen

Damit die Website dich als Autor der Übung aufführt, gehst du so vor:

In der Datei .meta/config.json der Übung:

  • Füge deinen GitHub-Benutzernamen zum Schlüssel authors hinzu

Dazu musst du dein Exercism-Konto mit GitHub verknüpfen. Das geht auf der Website im Bereich „Integrationen“ der Seite „Einstellungen“.

Note

Wer Übungen erstellt, erhält außerdem Reputation

Skript verwenden

Neuere Track-Repos können das Skript bin/add-practice-exercise (Quelle) verwenden, um neue Übungen hinzuzufügen:

bin/add-exercise -a <github_username> two-fer
Note

Wenn du an einem Track-Repo arbeitest, in dem diese Datei fehlt, kannst du sie über den oben stehenden Quelllink gerne in dein Repo kopieren.

Übung umsetzen

Sobald die Dateien aus der Vorlage erstellt sind, musst du:

  • Tests zur Testdatei hinzufügen
  • eine Beispielimplementierung hinzufügen
  • den Inhalt der Stub-Datei festlegen

Tests hinzufügen

Ein wesentlicher Teil beim Hinzufügen einer Übung ist das Schreiben von Tests. Grob gesagt gibt es zwei Möglichkeiten, eine der oben genannten Übungen umzusetzen:

  1. Die Tests von Grund auf selbst schreiben und dabei die Testfälle aus der canonical-data.json der Übung verwenden
  2. Die Tests aus der Implementierung eines anderen Tracks übernehmen (Tipp: Unter https://exercism.org/exercises/hello-world siehst du, welche Tracks eine bestimmte Übung umgesetzt haben).

Für die „Hello, World!“-Übung gibt es nur einen einzigen Testfall, daher ist jede der beiden Möglichkeiten in Ordnung.

Beispielimplementierung hinzufügen

Die Datei mit der Beispielimplementierung sollte den Code enthalten, der nötig ist, um die Tests zu bestehen.

Den Stub festlegen

Die Stub-Datei sollte eine fast funktionierende Lösung für die Tests enthalten, aber mit „Goodbye, Mars!“ statt „Hello, World!“. Tipp: Du kannst die Beispiellösung einfach kopieren, einfügen und anpassen.

Die Autoren der Übung aktualisieren

Wenn du mit der Übung fertig bist, füge bitte deinen GitHub-Benutzernamen zum Array "authors" in der Datei .meta/config.json der Übung hinzu. So stellen wir sicher, dass du korrekt als Ersteller der Übung genannt wirst.

Linting

Um zu überprüfen, ob die Übung korrekt eingerichtet ist, kannst du die eingebaute Lint-Funktion des configlet-Tools verwenden.

Der erste Schritt ist, das Tool configlet herunterzuladen. Dafür haben wir zwei Skripte erstellt:

  • bin/fetch-configlet: führe dies unter *nix oder macOS aus
  • bin/fetch-configlet.ps1: führe dies unter Windows aus

Wenn du eines dieser Skripte im Stammverzeichnis des Track-Repos ausführst, wird die Binärdatei bin/configlet bzw. bin/configlet.exe heruntergeladen.

Anschließend kannst du die Übung auf Korrektheit prüfen, indem du bin/configlet lint ausführst.

Note

Wahrscheinlich meldet configlet folgenden Fehler:

The `tags` array is empty:
/path/to/track/config.json

Dieser Fehler wird im Schritt Vorbereitung auf den Start behoben, also entweder:

  • ignoriere den Fehler (vorerst), oder
  • behebe den Fehler, indem du Tags hinzufügst
Note

Der configlet-Workflow führt automatisch configlet lint aus, sobald etwas nach main oder in einen Pull Request gepusht wird.