建立軌道


一個賽道由許多不同的部分組成。

中繼資料

賽道的設定與中繼資料都定義在config.json檔案中。它列出了賽道的練習、概念、編輯器設定,以及更多內容。請參閱 config.json 文件。

概念

賽道中所有的概念練習與實作練習都涉及_概念_。這些概念本身都是各自獨立的實體。更多資訊請參閱文件。

賽道裡概念練習所教授的這些概念,構成了_課程大綱_。 _課程大綱_會以_概念圖_的形式呈現給學生。 想了解如何為_課程大綱_建立概念圖,請參閱_概念圖_文件。

關於如何設計課程大綱的更多資訊,請參閱課程大綱文件。

練習

賽道有兩種類型的練習:

  • 概念練習:用來教學生一個或多個概念。更多資訊請參閱文件。
  • 實作練習:用來練習已經學會的概念。更多資訊請參閱文件。

深入探索

每個練習都有一個選用的「深入探索」區塊,可以包含:

  • 解題方法:同一個練習的不同解法
  • 文章:介紹這個練習有趣的地方
  • 社群影片:展示這個練習的影片,通常是有人從頭把練習解一遍

共用檔案

有些檔案不是個別練習專屬的,而是適用於_所有_練習。更多資訊請參閱文件。

文件

每個賽道都有幾個必備的文件檔案。更多資訊請參閱文件。

小工具

賽道的某些部分可以顯示在小工具中。

風格指南

所有文件都應遵循風格指南。Markdown 文件 也應遵循我們的 Markdown 標準。

範例

csharp
├── config
|   ├── exercise_readme.go.tmpl
|   └── maintainers.json
├── docs
|   ├── ABOUT.md
|   ├── INSTALLATION.md
|   ├── LEARNING.md
|   ├── RESOURCES.md
|   └── TESTS.md
├── concepts
|   └── numbers
|       ├── about.md
|       ├── introduction.md
|       └── links.json
└── exercises
|   ├── concept
|   |   └── cars-assemble
|   |       ├── .docs
|   |       |   ├── hints.md
|   |       |   ├── introduction.md
|   |       |   └── instructions.md
|   |       ├── .meta
|   |       |   ├── config.json
|   |       |   ├── design.md
|   |       |   └── Exemplar.cs (track-specific)
|   |       ├── CarsAssemble.cs (track-specific)
|   |       ├── CarsAssemble.csproj (track-specific)
|   |       └── CarsAssembleTests.cs (track-specific)
|   ├── practice
|   |   └── leap
|   |       └── .docs
|   |       |   └── instructions.md
|   |       └── .meta
|   |       |   ├── config.json
|   |       |   └── Example.cs (track-specific)
|   |       ├── Leap.cs (track-specific)
|   |       ├── Leap.csproj (track-specific)
|   |       └── LeapTests.cs (track-specific)
|   └── shared
|       └── .docs
|           ├── debug.md
|           ├── help.md
|           └── tests.md
└── config.json

維護

儲存庫權限

每個賽道都會(自動)被指派一個維護類別,這個類別會決定賽道維護者的 GitHub 儲存庫權限。

避免觸發不必要的測試執行

當你合併一個更動到某個練習的賽道 PR 時,它會觸發_所有_學生解答中最新已發佈的版本重新接受測試。 對於熱門的練習來說,這是個_非常_耗費資源的操作(極端例子:Python 的 Hello World 就有 70,000 次測試執行!)。

我們鼓勵你盡量避免不必要地這麼做。

如果合併的提交符合下列任一情況,解答不會重新測試:

  • 只更動到 .docs 或 .meta 檔案,或其他使用者不會接觸到的檔案
  • 或是在提交內容中包含 [no important files changed]

如果合併的提交同時符合下列兩點,解答會重新測試:

  • 提交內容中缺少 [no important files changed]
  • 而且更動到該練習下列其中一種檔案(依其 .meta/config.json檔案中的設定):
    • 測試檔案
    • 編輯器檔案
    • 失效檔案

一些範例:

  • Python#3423:只更動到文件,所以沒有執行測試
  • Python#3437:合併時加上了 [no important files changed],所以沒有執行測試
  • Csharp#2138:測試中的空白被移除了。關鍵字沒有被加上。測試於是被不必要地重新執行了。