configlet sync

將練習資料與 problem-specifications 儲存庫同步

Exercism track 上的練習題通常是依照 exercism/problem-specifications 儲存庫中的規格實作。

Exercism 刻意要求每個練習都要有自己的一份特定檔案（例如.docs/instructions.md），即使該練習已存在於problem-specifications中。

因此 configlet 有sync指令，可以檢查 track 上這類練習題是否與上游來源同步，並在有更新可用時更新它們。

有 3 種資料可以從problem-specifications更新：文件、中繼資料，以及測試。 另外還有一種資料可以從 track 層級config.json檔案填入：練習設定檔中的檔案路徑。

我們會在下方各節分別說明這些資料種類的檢查與更新方式，但先做個快速摘要：

  • configlet sync只會作用於 track 層級config.json檔案中已有的練習。 因此，如果你要在 track 上實作新的練習，並想用configlet sync加入初始檔案，請先把該練習加入 track 層級config.json檔案。 如果該練習還沒準備好開放給使用者，請將其status值設為wip。
  • 單純執行configlet sync不會對 track 做任何變更，並會檢查每個練習的每種資料。
  • 若只想處理部分資料種類，可搭配使用--docs、--filepaths、--metadata和--tests選項。
  • 若要互動式更新 track 上的資料，請使用--update選項。
  • 若要以非互動方式更新 track 上的文件、檔案路徑和中繼資料，請使用--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指令。 不過，當缺少必要的鍵（authors、files、blurb）時，configlet sync確實會加入這些鍵（可能為空）。 這比較不像「同步」，但更符合人體工學：實作新練習時，你可以用sync建立起始的.meta/config.json檔案。
  • configlet sync會移除規格中沒有的鍵。 仍然支援自訂的鍵／值配對：它們必須寫在名為custom的 JSON 物件內。
  • 當 configlet 結束時，若所有已看到的資料都已同步，結束代碼為 0；否則為 1。

請注意，在configlet 4.0.0-alpha.34版及更早版本中，sync指令只會作用於測試。

用法

sync指令可以用來從「problem-specifications」檢查或更新練習題的文件、中繼資料和測試。 它也可以從 track 的「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儲存庫衍生的練習題必須有.docs/instructions.md檔案（也可能有.docs/introduction.md檔案），其中包含來自problem-specifications的練習文件。

若要檢查 track 上每個練習題是否有可用的文件更新（若至少有一個更新可用，會以非零結束代碼結束）：

configlet sync --docs

若要互動式更新每個練習題的文件，請加上--update選項（或簡寫-u）：

configlet sync --docs --update

若要以非互動方式更新每個練習題的文件，請加上--yes選項（或簡寫-y）：

configlet sync --docs --update --yes

若要只處理單一練習題，請使用--exercise選項（或簡寫-e）。 例如，若要以非互動方式更新prime-factors練習的文件：

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

中繼資料

track 上的每個練習都必須有.meta/config.json檔案。 對於從problem-specifications儲存庫衍生的練習題，這個檔案應包含對應上游metadata.toml檔案中有的blurb、source和source_url鍵／值配對。

若要檢查每個練習題是否有可用的中繼資料更新（若至少有一個更新可用，會以非零結束代碼結束）：

configlet sync --metadata

若要互動式更新每個練習題的中繼資料，請加上--update選項（或簡寫-u）：

configlet sync --metadata --update

若要以非互動方式更新每個練習題的中繼資料，請加上--yes選項（或簡寫-y）：

configlet sync --metadata --update --yes

若要只處理單一練習題，請使用--exercise選項（或簡寫-e）。 例如，若要以非互動方式更新prime-factors練習的中繼資料：

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

測試

如果 track 實作了某個練習，而該練習的測試資料存在於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"

在這個例子中，該 track 選擇實作三個可用測試中的兩個。 如果 track 使用測試產生器來產生練習的測試套件，就必須使用tests.toml檔案的內容來決定要在產生的測試套件中包含哪些測試。

若要檢查每個練習題的tests.toml檔案是否有可用的測試更新（如果練習的標準資料中至少有一個測試案例未出現在tests.toml中，則會以非零結束代碼結束）：

configlet sync --tests

若要互動式更新每個練習題的tests.toml檔案，請加上--update選項：

configlet sync --tests --update

對於每個缺少的測試，這會提示使用者選擇要包含、排除或略過它，並相應地更新對應的tests.toml檔案。 當使用者完成某個練習的選擇後，Configlet 會寫入該練習的tests.toml檔案。 這表示你可以在提示畫面終止 configlet（例如在終端機按 Ctrl-C），而最多只會失去一個練習的同步決定。

若要以非互動方式包含每個未見過的測試案例，請使用--tests include。 例如，若要對名為prime-factors的練習這麼做：

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

記得要在 track 上實際實作這些測試喔！

檔案路徑

最後，sync指令也處理來自不是problem-specifications的來源的「同步」：track 層級config.json檔案。 每個概念練習和練習題都必須有.meta/config.json檔案，其中包含files物件，用來指定該練習所用檔案的（相對）位置。 這類檔案路徑通常遵循簡單的模式，因此 configlet 可以從 track 層級config.json檔案中files鍵的模式填入練習層級的值。

若要檢查 track 上每個概念練習和練習題都有完整填入的files鍵（或至少有一個無法從 track 層級files鍵填入的項目）：

configlet sync --filepaths

（請注意，當練習的files鍵缺少或為空時，configlet lint也會產生錯誤。）

若要從 track 層級files鍵的模式填入每個概念練習和練習題的練習層級files鍵中空或缺少的值：

configlet sync --filepaths --update

若要非互動地對名為prime-factors的單一練習執行這項操作：

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

在 track 上新增練習時使用sync

在 track 上新增練習時，sync指令很有用。 如果你要新增一個名為foo的練習題，而該練習存在於problem-specifications中，一種可行的工作流程是：

  1. 手動在 track 層級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. 新增其他必要的檔案。