Eine Praxisübung hinzufügen

Dieses Dokument erklärt, wie du eine neue Practice Exercise hinzufügst.

Übung auswählen

Am einfachsten findest du heraus, welche Practice Exercises noch nicht implementiert sind, wenn du die Build-Seite des Tracks öffnest (z. B. https://exercism.org/tracks/csharp/build) und dort den Abschnitt „Practice Exercises“ ansiehst.

Caution

Die Daten auf der Build-Seite werden einmal pro Tag aktualisiert.

Übung als Gerüst anlegen

Du kannst eine neue Practice Exercise schnell als Gerüst anlegen, indem du das Skript bin/add-practice-exercise (Quellcode) im Stammverzeichnis des Tracks ausführst:

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

Optional kannst du auch die Schwierigkeit der Übung (über -d) und/oder den GitHub-Nutzernamen des Autors (über -a) angeben:

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

Wenn du an einem Track-Repository arbeitest, in dem diese Datei fehlt, kannst du sie über den oben stehenden Quellcode-Link in dein Repository kopieren.

Übung implementieren

Sobald die Gerüstdateien angelegt sind, musst du noch:

  • Tests in die Testdatei einfügen
  • Eine Beispielimplementierung hinzufügen
  • Den Inhalt der Stub-Datei festlegen
  • In der Datei .meta/config.json der Übung:
    • Den GitHub-Nutzernamen der Autoren der Übung zum Schlüssel authors hinzufügen
  • In der Datei config.json des Tracks:
    • Die Schwierigkeit der Übung prüfen bzw. aktualisieren
    • Konzepte zum Schlüssel practices hinzufügen (nur nötig, wenn der Track Concept Exercises hat)
    • Konzepte zum Schlüssel prerequisites hinzufügen (nur nötig, wenn der Track Concept Exercises hat)

Tests hinzufügen

Ein wichtiger Teil beim Hinzufügen einer Übung sind die Tests. Grob gesagt gibt es zwei Möglichkeiten, Tests für eine Practice Exercise hinzuzufügen:

  1. Die Tests von Grund auf selbst schreiben und dabei die Testfälle aus der Datei canonical-data.json der Übung verwenden, die du im problem-specifications-Repository findest.
  2. Die Tests aus der Implementierung eines anderen Tracks übernehmen (Tipp: Unter https://exercism.org/exercises/<slug> siehst du, welche Tracks eine bestimmte Übung implementiert haben).

Die zweite Möglichkeit ist oft besonders verlockend, weil du damit schnell Ergebnisse erzielst. Bedenke aber, dass du die Implementierung an deinen Track anpassen solltest. Manche Tracks arbeiten zum Beispiel nicht mit Klassen, sondern nur mit Funktionen. Wenn dein Track normalerweise mit Objekten arbeitet, solltest du die Implementierung so anpassen, dass sie zu deinem Track passt.

Note

Manche Tracks verwenden einen Test-Generator, um die Testdatei(en) einer Übung automatisch (neu) zu erzeugen. Schau in der Dokumentation des Tracks nach, ob es einen Test-Generator gibt und wie du ihn verwendest.

Beispielimplementierung hinzufügen

Damit sichergestellt ist, dass sich Code schreiben lässt, der die Tests besteht, muss eine Beispielimplementierung hinzugefügt werden.

Note

Der Code muss nicht idiomatisch sein, er muss nur die Tests bestehen.

Du kannst prüfen, ob die Beispielimplementierung alle Tests besteht, indem du das Skript bin/verify-exercises (Quellcode) im Stammverzeichnis des Tracks ausführst:

bin/verify-exercises <exercise-slug>

Prüfe anhand der Ausgabe, ob die Beispielimplementierung alle Tests besteht.

Note

Wenn du an einem Track-Repository arbeitest, in dem diese Datei fehlt, kannst du sie über den oben stehenden Quellcode-Link in dein Repository kopieren.

Advanced

Im Hintergrund erledigt das Skript bin/verify-exercises mehrere Dinge:

  • Es kopiert die Übung in ein temporäres Verzeichnis
  • Es überschreibt die Stub-Datei(en) mit der bzw. den Beispielimplementierungsdateien
  • Wenn die Testdatei übersprungene Tests enthält, werden diese wieder aktiviert
  • Es führt die Tests aus

Stub-Datei(en) hinzufügen

Die Stub-Implementierungsdatei(en) geben den Lernenden einen Ausgangspunkt.

Wir empfehlen, Stub-Dateien mit möglichst wenig Code anzulegen, sodass:

  • die Lernenden sofort mit der Implementierung der Logik beginnen können, um die Tests zu bestehen
  • keine „seltsamen“ Syntaxfehler auftreten

In der Praxis heißt das, dass du die Funktionen bzw. Methoden definierst, die die Testsuite prüft. Den Tracks ist freigestellt, wie sie diesen Code aufsetzen, solange sie dafür sorgen, dass der Stub-Code anfangs alle Tests fehlschlagen lässt.

Beispiele

Python:

def two_fer(name):
    pass

Kotlin:

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

Übung mit dem Linter prüfen

Zum Schluss führst du den Linter aus, um zu prüfen, ob die (Konfigurations-)Dateien des Tracks korrekt aufgebaut sind, sowohl syntaktisch als auch semantisch.

Stelle zuerst sicher, dass du die neueste Version von configlet hast, und führe dazu aus:

bin/fetch-configlet

Führe dann den Linter aus:

bin/configlet lint

Prüfe anhand der Ausgabe, ob alles in Ordnung ist.

Pull Request einreichen

Wenn alles in Ordnung ist, kannst du einen Pull Request für das Repository des Tracks einreichen.

Lies vor dem Einreichen bitte den Contributors Pull Request Guide und den Pull Request Guide.

Achte darauf, dass in der PR-Beschreibung die hinzugefügte Übung genannt wird.