Configlet

Exercism 上所有內容的標準規格

configlet 是一套工具，用來協助賽道維護者維護自己的賽道。

檢查

configlet 的主要功能是進行_檢查_：確認賽道的（設定）檔案在結構上是否正確，包括語法和語意兩方面。 設定錯誤的賽道可能無法正確同步、在網站上顯示錯誤，或帶給使用者不佳的體驗，因此 configlet 的防護機制在維護 Exercism 的完整性上扮演重要角色。 檢查工具所檢查的完整規則清單請見這裡。

產生文件

configlet 的次要功能是產生文件。configlet 可以產生兩種文件：

  1. 概念練習的 introduction.md檔案。
  2. 練習題的 instructions.md檔案。

這些文件是如何產生的，請見這裡。

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

configlet 的第三項功能是為練習題提供各種資料。

Exercism 賽道上的練習題通常是根據 exercism/problem-specifications 儲存庫中的規格實作而成。

Exercism 刻意要求每個練習都擁有某些檔案的專屬副本（例如.docs/instructions.md），即使該練習已經存在於problem-specifications中也是如此。 因此 configlet 提供了sync指令，可以檢查賽道上這類練習題是否與上游來源保持同步，並在有更新可用時更新它們。

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

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

為了追蹤某個特定練習題實作了哪些測試，該練習_必須_包含.meta/tests.toml檔案。 這個檔案中的測試以其 UUID 來識別，每個測試都有一個布林值，表示該測試是否由該練習實作。

關於如何同步練習各部分的詳細說明，請見這裡。

建立檔案

Configlet 可以用來快速為新的解題思路、文章或練習建立檔案。

想進一步了解如何建立這些檔案，請見這裡。

產生 UUID

練習、賽道和概念都以 UUID 來識別。

產生 UUID 的方法請見這裡。

格式化

Configlet 有fmt指令，可協助讓賽道儲存庫中的 JSON 檔案格式保持一致。 fmt指令會格式化下列檔案：

  • config.json
  • exercises/{concept,practice}/*/.approaches/config.json
  • exercises/{concept,practice}/*/.articles/config.json
  • exercises/{concept,practice}/*/.meta/config.json

想進一步了解格式化指令，請見這裡。

安裝

configlet 以獨立二進位檔的形式發佈。每個賽道都應該有一個bin/fetch-configlet指令碼，也可能會有bin/fetch-configlet.ps1指令碼。前者是 bash 指令碼，後者是 PowerShell 指令碼。

執行其中一個指令碼會把最新版的 configlet 下載到bin目錄。接著你就可以分別執行bin/configlet或bin/configlet.exe來使用 configlet。

CI

所有賽道都應該在其 CI 設定中整合 configlet 的檢查功能。 最簡單的做法是使用 configlet CI GitHub action。