Separate document for test runner building (#519)

building/config.json

@@ -632,17 +632,29 @@
     "path": "building/tracks/new/add-first-exercise.md",
     "title": "Add the first exercise"
   },
+  {
+    "uuid": "975a3a67-5d5e-4022-b363-a40661095c93",
+    "slug": "tracks/new/setup-continuous-integration",
+    "path": "building/tracks/new/setup-continuous-integration.md",
+    "title": "Setup Continuous Integration"
+  },
   {
     "uuid": "c8f1ff4d-55f8-447e-b5e7-4a87f1e341f7",
     "slug": "tracks/new/add-initial-exercises",
     "path": "building/tracks/new/add-initial-exercises.md",
     "title": "Add initial exercises"
   },
   {
-    "uuid": "975a3a67-5d5e-4022-b363-a40661095c93",
-    "slug": "tracks/new/setup-continuous-integration",
-    "path": "building/tracks/new/setup-continuous-integration.md",
-    "title": "Setup Continuous Integration"
+    "uuid": "ae9c8c65-2c39-48d5-b647-4189cff77862",
+    "slug": "tracks/new/build-test-runner",
+    "path": "building/tracks/new/build-test-runner.md",
+    "title": "Build test runner"
+  },
+  {
+    "uuid": "0113174d-314d-4255-a300-32150dc32179",
+    "slug": "tracks/new/configure-tooling",
+    "path": "building/tracks/new/configure-tooling.md",
+    "title": "Configure tooling"
   },
   {
     "uuid": "3bc94082-8fa3-4129-bca7-c1892cba3ed4",
@@ -662,24 +674,18 @@
     "path": "building/tracks/new/launch.md",
     "title": "Launch!"
   },
+  {
+    "uuid": "f697a7c1-ad33-460c-8458-18cd6d149920",
+    "slug": "tracks/new/implement-tooling",
+    "path": "building/tracks/new/implement-tooling.md",
+    "title": "Implement additional tooling"
+  },
   {
     "uuid": "65fe2eb3-bd67-4312-9e9d-d7334cdcbdcf",
     "slug": "tracks/new/prepare-for-contributions",
     "path": "building/tracks/new/prepare-for-contributions.md",
     "title": "Prepare for open source contributions from strangers"
   },
-  {
-    "uuid": "0113174d-314d-4255-a300-32150dc32179",
-    "slug": "tracks/new/configure-tooling",
-    "path": "building/tracks/new/configure-tooling.md",
-    "title": "Configure tooling"
-  },
-  {
-    "uuid": "f697a7c1-ad33-460c-8458-18cd6d149920",
-    "slug": "tracks/new/implement-tooling",
-    "path": "building/tracks/new/implement-tooling.md",
-    "title": "Implement tooling"
-  },
   {
     "uuid": "11894561-be89-471f-ac4e-581449add2bd",
     "slug": "tracks",

building/tracks/new/README.md

@@ -10,11 +10,12 @@ Once you've completed that step, the next steps are:
 - [Select programming language variant](/docs/building/tracks/new/select-programming-language-variant) (if applicable)
 - [Select testing framework](/docs/building/tracks/new/select-testing-framework)
 - [Add the first exercise](/docs/building/tracks/new/add-first-exercise)
-- [Add initial exercises](/docs/building/tracks/new/add-initial-exercises)
 - [Setup Continuous Integration](/docs/building/tracks/new/setup-continuous-integration)
+- [Add initial exercises](/docs/building/tracks/new/add-initial-exercises)
+- [Build test runner](/docs/building/tracks/new/build-test-runner)
+- [Configure tooling](/docs/building/tracks/new/configure-tooling)
 - [Prepare for launch](/docs/building/tracks/new/prepare-for-launch)
 - [Find Maintainers](/docs/building/tracks/new/find-maintainers)
 - [Launch!](/docs/building/tracks/new/launch)
-- [Configure tooling](/docs/building/tracks/new/configure-tooling)
-- [Implement tooling](/docs/building/tracks/new/implement-tooling)
+- [Implement additional tooling](/docs/building/tracks/new/implement-tooling)
 - [Prepare for open source contributions from strangers](/docs/building/tracks/new/prepare-for-contributions)

building/tracks/new/build-test-runner.md

@@ -0,0 +1,29 @@
+# Build test runner
+
+The test runner is an essential bit of tooling that allows:
+
+- The website to automatically verify if an iteration passes all the tests.
+- Students to solve exercises using the [in-browser editor](/docs/using/solving-exercises/using-the-online-editor) ([no CLI needed](/docs/using/solving-exercises/working-locally)).
+
+To get started building a Test Runner, check the [Creating a Test Runner from scratch](/docs/building/tooling/test-runners/creating-from-scratch) document.
+
+## Implementation
+
+Track tooling is usually (mostly) written in the track's language.
+
+```exercism/caution
+While you're free to use other languages, each additional language will make it harder to maintain or contribute to the track.
+Therefore, we recommend using the track's language where possible, because it makes maintaining or contributing easier.
+```
+
+## Deployment
+
+The test runner is packaged and run as a [Docker container](/docs/building/tooling/docker).
+Test runner Docker images are deployed automatically using a [GitHub Actions workflow](https://github.com/exercism/generic-test-runner/blob/main/.github/workflows/docker.yml).
+
+## Testing
+
+Once a test runner has been built, you could use its Docker image in your track's CI setup to verify the track's exercises.
+The main benefit of this approach is that it better mimics the production setup; in other words, you can be more confident that things also work in production.
+A possible downside is that it might slow down the CI workflow.
+It is up to you, the maintainer, to decide which approach works best for your track.

building/tracks/new/configure-tooling.md

@@ -1,9 +1,12 @@
 # Configure tooling
 
-There are three bits of tooling that you can optionally tweak for your track:
+There are three bits of tooling that you should tweak for your track:
 
-- The **[Lines of Code Counter](/docs/building/tooling/lines-of-code-counter)**
-- The **[Snippet Extractor](/docs/building/tooling/snippet-extractor)**
-- The **[Exercism CLI](/docs/building/tooling/cli)**
+- The **[Lines of Code Counter](/docs/building/tooling/lines-of-code-counter)**: this tool is tasked with counting the lines of code for each submitted iteration.
+- The **[Snippet Extractor](/docs/building/tooling/snippet-extractor)**: this tool extracts a snippet for each iteration, which is shown on the website.
+- The **[Exercism CLI](/docs/building/tooling/cli)**: this tool is used by students to work on a track locally, on their own machine.
 
-While tweaking these tools is optional, doing so can make your track's integration into the website just _that_ bit better.
+```exercism/note
+Even though tweaking these tools is optional, it'll make your track's integration into the website _much_ better.
+Therefore, we highly recommend you tweak all three tools.
+```

building/tracks/new/implement-tooling.md

@@ -1,6 +1,6 @@
 # Implement tooling
 
-After launching the track with the first 20+ exercises, the focus should shift to implementing the [track tooling](/docs/building/tooling).
+After launching the track with the first 20+ exercises and a test runner, the focus should shift to implementing [additional track tooling](/docs/building/tooling).
 
 There are two types of track tooling:
 
@@ -24,14 +24,9 @@ To help with track maintenance, one can also build:
 ## Which tool to implement?
 
 The production tools are more important than maintenance tools.
-Of the three production tools, the Test Runner should be implemented first as it enables:
+At this point, you should have implemented a Test Runner (if not, check the [Build a test runner docs](/docs/building/tracks/new/build-test-runner)).
 
-- Students to solve exercises using the [in-browser editor](/docs/using/solving-exercises/using-the-online-editor) ([no CLI needed](/docs/using/solving-exercises/working-locally)).
-- The website to automatically verify if an iteration passes all the tests.
-
-To get started building a Test Runner, check the [Creating a Test Runner from scratch](/docs/building/tooling/test-runners/creating-from-scratch) document.
-
-Once a test runner has been built, the next tool to work on is the Representer.
+Having built a test runner, the next tool to work on is the Representer.
 There is some overlap between the goals of the Representer and the Analyzer, but we recommend building the Representer first for the following reasons:
 
 - Representers are usually (far) easier to implement
@@ -58,6 +53,6 @@ Therefore, we recommend using the track's language where possible, because it ma
 ## Deployment
 
 Production tools are packaged and run as a [Docker container](/docs/building/tooling/docker).
-Tooling images are deployed automatically using a [Docker workflow](https://github.com/exercism/generic-test-runner/blob/main/.github/workflows/docker.yml).
+Tooling Docker images are deployed automatically using a [GitHub Actions workflow](https://github.com/exercism/generic-test-runner/blob/main/.github/workflows/docker.yml).
 
 Maintenance tools are _not_ deployed.