プラクティス演習を追加する

このドキュメントでは、新しいプラクティス演習を追加する方法を説明します。

演習を選ぶ

まだ実装されていないプラクティス演習を確認する最も簡単な方法は、トラックのビルドページ（例：https://exercism.org/tracks/csharp/build）を開き、「プラクティス演習」セクションを確認することです。

Caution

ビルドページのデータは、1日に1回だけ更新されます。

演習のひな形を作成する

新しいプラクティス演習のひな形は、トラックのルートディレクトリでbin/add-practice-exerciseスクリプト（ソース）を実行すると、すばやく作成できます：

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

オプションとして、演習の難易度（-dで指定）や作者のGitHubユーザー名（-aで指定）も指定できます：

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

このファイルがないトラックリポジトリで作業している場合は、上記のソースリンクを使って自分のリポジトリにコピーしてかまいません。

演習を実装する

ひな形のファイルを作成したら、次は次の作業を行います：

  • テストファイルにテストを追加する
  • 実装例を追加する
  • スタブファイルの内容を定義する
  • 演習の.meta/config.jsonファイルで：
    • 演習の作者のGitHubユーザー名をauthorsキーに追加する
  • トラックのconfig.jsonファイルで：
    • 演習の難易度を確認・更新する
    • practicesキーに概念を追加する（トラックにコンセプト演習がある場合のみ）
    • prerequisitesキーに概念を追加する（トラックにコンセプト演習がある場合のみ）

テストを追加する

演習を追加するうえで欠かせないのが、テストの追加です。 プラクティス演習のテストを追加する方法は、大きく分けて2つあります：

  1. problem-specificationsリポジトリにある、その演習のcanonical-data.jsonファイルのテストケースを使って、テストを一から実装する。
  2. 別のトラックの実装からテストを移植する（ヒント：https://exercism.org/exercises/<slug>にアクセスすると、特定の演習をどのトラックが実装しているかの概要がわかります）。

2つ目の方法は、すぐに結果が得られるので、特に魅力的に思えるかもしれません。 ただし、自分のトラックに最も合うように実装を調整することを忘れないでください。 たとえば、クラスを使わず関数だけで扱うトラックもあります。 一方で、自分のトラックが通常オブジェクトを扱うなら、トラックに最も合う形に実装を適応させるべきです。

Note

テストファイルを自動で（再）生成するために、テストジェネレーターを使うトラックもあります。 テストジェネレーターがあるかどうか、ある場合はその使い方を、トラックのドキュメントで確認してください。

実装例を追加する

テストにパスするコードが書けることを確かめるために、実装例を追加する必要があります。

Note

コードは必ずしも慣用的である必要はありません。テストにパスしさえすればよいのです。

実装例がすべてのテストにパスするかどうかは、トラックのルートディレクトリでbin/verify-exercisesスクリプト（ソース）を実行して確認できます：

bin/verify-exercises <exercise-slug>

出力を使って、実装例がすべてのテストにパスしていることを確認してください。

Note

このファイルがないトラックリポジトリで作業している場合は、上記のソースリンクを使って自分のリポジトリにコピーしてかまいません。

Advanced

内部では、bin/verify-exercisesスクリプトが次のようないくつかの処理を行います：

  • 演習を一時ディレクトリにコピーする
  • スタブファイルを実装例のファイルで上書きする
  • テストファイルにスキップされたテストがある場合は、そのスキップを解除する
  • テストを実行する

スタブファイルを追加する

スタブ実装のファイルは、学習者が取りかかるための出発点になります。

スタブファイルには、次の条件を満たす最小限のコードを書くことをおすすめします：

  • 学習者がすぐに、テストにパスするロジックを実装し始められる
  • 学習者が「妙な」構文エラーに直面しない

実際には、これはテストスイートがテストする関数やメソッドを定義することを意味します。 スタブコードが最初はすべてのテストに失敗することさえ守られていれば、このコードをどのように用意するかはトラックの自由です。

例

Python:

def two_fer(name):
    pass

Kotlin:

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

演習をリントする

最後のステップは、リンターを実行して、トラックの（設定）ファイルが構文的にも意味的にも正しく構成されているかを確認することです。

まず、次のコマンドを実行して、configletの最新バージョンを使っていることを確認します：

bin/fetch-configlet

次に、次のコマンドを実行してリンターを実行します：

bin/configlet lint

出力を使って、すべて問題ないことを確認してください。

プルリクエストを作成する

すべて問題なければ、トラックのリポジトリにプルリクエストを作成できます。

作成する前に、コントリビューター向けプルリクエストガイドとプルリクエストガイドをお読みください。

PRの説明に、追加する演習を必ず記載してください。