新增練習題

這份文件會說明如何新增一個新的練習。

選擇練習

要確認還有哪些練習尚未實作，最簡單的方法就是前往軌道的建置頁面（例如 https://exercism.org/tracks/csharp/build），然後查看「練習」區塊。

Caution

建置頁面上的資料每天只更新一次。

建立練習骨架

你可以從軌道的根目錄執行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 鍵（只有當軌道有概念練習時才需要）

加入測試

新增練習時，一個關鍵環節就是加入測試。 大致來說，為練習加入測試時有以下選擇：

  1. 從頭實作測試，使用練習的 canonical-data.json 檔案中的測試案例，該檔案位於 problem-specifications 儲存庫。
  2. 從其他軌道的實作移植測試（提示：前往 https://exercism.org/exercises/<slug>，就能大致了解有哪些軌道實作了某個練習）。

後者可能特別吸引人，因為它能讓你很快看到成果。 不過請記得，你應該調整實作，讓它最符合你的軌道。 舉例來說，有些軌道不使用類別，只使用函式。 但如果你的軌道通常使用物件，就應該把實作調整成最符合你軌道的樣子。

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

請根據輸出結果，確認一切正常。

提交 Pull Request

一切就緒之後，你就可以向軌道的儲存庫提交 Pull Request。

提交之前，請先閱讀貢獻者 Pull Request 指南和 Pull Request 指南。

請確保 PR 說明中列出了要新增的練習。