configlet sync

problem-specificationsリポジトリと演習データを同期する

Exercismトラックの練習問題は、しばしばexercism/problem-specificationsリポジトリの仕様をもとに実装されます。

Exercismでは、たとえその演習がproblem-specificationsに存在していても、すべての演習が特定のファイル（.docs/instructions.mdなど）のコピーをそれぞれ持つことが意図的に求められています。 そのためconfigletにはsyncコマンドがあり、トラック上のそうした練習問題が上流のソースと同期しているかを確認し、更新があれば更新できます。

problem-specificationsから更新できるデータには3種類あります。ドキュメント、メタデータ、テストです。 また、トラックレベルのconfig.jsonファイルから設定できるデータが1種類あります。演習の設定ファイルにあるファイルパスです。

これらのデータ種別の確認と更新については、以下の各セクションで説明しますが、手短にまとめると次のとおりです。

  • configlet syncが操作するのは、トラックレベルのconfig.jsonファイルに存在する演習だけです。 そのため、トラックに新しい演習を実装していて、configlet syncで初期ファイルを追加したい場合は、まずその演習をトラックレベルのconfig.jsonファイルに追加してください。 まだユーザーに公開する準備ができていない演習なら、statusの値をwipに設定してください。
  • オプションを付けないconfiglet syncはトラックに何も変更せず、すべての演習についてすべてのデータ種別を確認します。
  • 一部のデータ種別だけを操作するには、--docs、--filepaths、--metadata、--testsのオプションを適宜組み合わせて使います。
  • トラック上のデータを対話的に更新するには、--updateオプションを使います。
  • トラック上のドキュメント、ファイルパス、メタデータを非対話的に更新するには、--update --yesを使います。
  • ある演習について、まだ取り込んでいないすべてのテストを非対話的に取り込むには、たとえば--update --tests include --exercise prime-factorsを使います。
  • problem-specificationsリポジトリのダウンロードを省略するには、--offline --prob-specs-dir /path/to/local/problem-specificationsを追加します。
  • configlet syncは更新時に演習の.meta/config.jsonファイルのキーの順序を保とうとすることに注意してください。 同期せずにこれらのファイルを正規の形式で書き出すには、configlet fmtコマンドを使ってください。 ただしconfiglet syncは、必須キー（authors、files、blurb）が欠けている場合は（空の場合もある）それらを追加_します_。 これは「同期らしさ」には欠けますが、より使い勝手が良いです。新しい演習を実装するときに、syncを使ってスターターの.meta/config.jsonファイルを作成できます。
  • configlet syncは仕様にないキーを削除します。 カスタムのキーと値のペアは引き続きサポートされます。customという名前のJSONオブジェクトの中に書く必要があります。
  • 終了コードは、configletの終了時に確認対象のデータがすべて同期されていれば0、そうでなければ1です。

configletのリリース4.0.0-alpha.34以前では、syncコマンドはテストだけを操作していたことに注意してください。

使い方

syncコマンドは、'problem-specifications'から練習問題のドキュメント、メタデータ、テストを確認または更新するために使えます。 また、トラックの'config.json'から概念演習・練習問題の欠けているfilesの値を確認または設定するのにも使えます。

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)

ドキュメント

problem-specificationsリポジトリから派生した練習問題には、problem-specificationsの演習ドキュメントを含む.docs/instructions.mdファイル（および場合によっては.docs/introduction.mdファイルも）がなければなりません。

トラック上のすべての練習問題について、利用可能なドキュメントの更新があるか確認するには（少なくとも1つ更新があれば非ゼロの終了コードで終了します）：

configlet sync --docs

すべての練習問題のドキュメントを対話的に更新するには、--updateオプション（短縮形は-u）を追加します：

configlet sync --docs --update

すべての練習問題のドキュメントを非対話的に更新するには、--yesオプション（短縮形は-y）を追加します：

configlet sync --docs --update --yes

1つの練習問題だけを操作するには、--exerciseオプション（短縮形は-e）を使います。 たとえば、prime-factors演習のドキュメントを非対話的に更新するには：

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

メタデータ

トラック上のすべての演習には.meta/config.jsonファイルがなければなりません。 problem-specificationsリポジトリから派生した練習問題では、このファイルに、対応する上流のmetadata.tomlファイルに存在するblurb、source、source_urlのキーと値のペアが含まれている必要があります。

すべての練習問題について、利用可能なメタデータの更新があるか確認するには（少なくとも1つ更新があれば非ゼロの終了コードで終了します）：

configlet sync --metadata

すべての練習問題のメタデータを対話的に更新するには、--updateオプション（短縮形は-u）を追加します：

configlet sync --metadata --update

すべての練習問題のメタデータを非対話的に更新するには、--yesオプション（短縮形は-y）を追加します：

configlet sync --metadata --update --yes

1つの練習問題だけを操作するには、--exerciseオプション（短縮形は-e）を使います。 たとえば、prime-factors演習のメタデータを非対話的に更新するには：

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

テスト

トラックが、problem-specificationsリポジトリにテストデータが存在する演習を実装する場合、その演習には.meta/tests.tomlファイルが_必ず_含まれていなければなりません。 tests.tomlファイルの目的は、どのテストがその演習で実装されているかを追跡することです。 このファイルのテストはUUIDで識別され、各テストには、その演習で実装されているかどうかを示す真偽値が付きます。

tests.tomlファイルは次の形式です。

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

この場合、トラックは利用可能な3つのテストのうち2つを実装することを選んでいます。 トラックが_テストジェネレーター_を使って演習のテストスイートを生成する場合、tests.tomlファイルの内容を使って、生成するテストスイートにどのテストを含めるかを決め_なければなりません_。

すべての練習問題のtests.tomlファイルについて、利用可能なテストの更新があるか確認するには（その演習の正規データに現れるのにtests.tomlにないテストケースが少なくとも1つあれば非ゼロの終了コードで終了します）：

configlet sync --tests

すべての練習問題のtests.tomlファイルを対話的に更新するには、--updateオプションを追加します：

configlet sync --tests --update

欠けているテストごとに、それを含めるか除外するかスキップするかを選ぶようユーザーに促し、それに応じて対応するtests.tomlファイルを更新します。 configletは、ユーザーがその演習についての選択を終えると、その演習のtests.tomlファイルを書き込みます。 つまり、プロンプトの途中でconfigletを終了しても（たとえばターミナルでCtrl-Cを押す）、失われる同期の判断は多くとも1つの演習分だけです。

まだ取り込んでいないすべてのテストケースを非対話的に取り込むには、--tests includeを使います。 たとえば、prime-factorsという名前の演習でこれを行うには：

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

忘れずに、トラック上でこれらのテストを実際に実装しましょう！

ファイルパス

最後に、syncコマンドはproblem-specifications以外のソース、つまりトラックレベルのconfig.jsonファイルからの「同期」も扱います。 すべての概念演習と練習問題には、その演習が使うファイルの（相対）位置を指定するfilesオブジェクトを持つ.meta/config.jsonファイルがなければなりません。 そうしたファイルパスはたいてい単純なパターンに従うので、configletはトラックレベルのconfig.jsonファイルのfilesキーのパターンから、演習レベルの値を設定できます。

トラック上のすべての概念演習と練習問題が、完全に設定されたfilesキーを持つこと（または少なくとも、トラックレベルのfilesキーからは設定できないfilesキーを持つこと）を確認するには：

configlet sync --filepaths

（演習のfilesキーが欠けている、または空の場合、configlet lintもエラーを出すことに注意してください。）

すべての概念演習と練習問題について、演習レベルのfilesキーの空または欠けている値を、トラックレベルのfilesキーのパターンから設定するには：

configlet sync --filepaths --update

これを非対話的に、prime-factorsという名前の1つの演習だけに対して行うには：

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

トラックに新しい演習を追加するときにsyncを使う

syncコマンドは、トラックに新しい演習を追加するときに役立ちます。 problem-specificationsに存在するfooという名前の練習問題を追加する場合、考えられるワークフローの1つは次のとおりです。

  1. トラックレベルのconfig.jsonファイルに、演習fooのエントリーを手動で追加します。 これでその演習がconfiglet syncから見えるようになります。
  2. configlet sync --docs --filepaths --metadata -uy -e fooを実行して、その演習のドキュメントと、files、blurb、そしておそらくsourceとsource_urlの値が設定されたスターターの.meta/config.jsonファイルを作成します。
  3. 演習の.meta/config.jsonファイルを好みに合わせて編集します。 たとえば、authors配列に自分自身を追加します。
  4. configlet sync --tests include -u -e fooを実行して、すべてのテストが含まれた.meta/tests.tomlファイルを作成します。
  5. その.meta/tests.tomlファイルを見て、その演習で実装しないテストケースにinclude = falseを追加します。
  6. .meta/tests.tomlに含めたテストに合わせて、その演習のテストを実装します。
  7. その他の必要なファイルを追加します。