Start documenting workflows (#560)

building/config.json

@@ -667,6 +667,12 @@
     "path": "building/tracks/ci/workflows.md",
     "title": "Workflows"
   },
+  {
+    "uuid": "753dfe68-af5f-466e-b9a1-5797b6088ab0",
+    "slug": "tracks/ci/workflows/configlet",
+    "path": "building/tracks/ci/workflows/configlet.md",
+    "title": "configlet workflow"
+  },
   {
     "uuid": "191b0fa1-96e2-48a6-ad2e-c34f57443799",
     "slug": "tracks/ci/migrating-from-travis",

building/configlet/README.md

@@ -51,7 +51,13 @@ How to generate UUIDs can be found [here](/docs/building/configlet/uuid).
 ## Formatting
 
 Configlet has a `fmt` command to help with consistent formatting of the JSON files in the track repo.
-The `fmt` command currently only operates on the exercise `.meta/config.json` files but it is likely to operate on all the track JSON files in the future.
+The `fmt` command formats the following files:
+
+- `config.json`
+- `exercises/{concept,practice}/*/.approaches/config.json`
+- `exercises/{concept,practice}/*/.articles/config.json`
+- `exercises/{concept,practice}/*/.meta/config.json`
+
 You can learn more about the format command [here](/docs/building/configlet/format).
 
 ## Installation

building/configlet/format.md

@@ -3,14 +3,17 @@
 An Exercism track repo has many JSON files, including:
 
 - The track `config.json` file.
-
 - For each concept, a `.meta/config.json` and `links.json` file.
-
 - For each Concept Exercise or Practice Exercise, a `.meta/config.json` file.
 
 These files are more readable if they have a consistent formatting Exercism-wide, and so configlet has a `fmt` command for rewriting a track's JSON files in a canonical form.
 
-The `fmt` command currently operates on the exercise `.meta/config.json` files and the track `config.json` file, but it is likely to operate on all the track JSON files in the future.
+The `fmt` command formats the following files:
+
+- `config.json`
+- `exercises/{concept,practice}/*/.approaches/config.json`
+- `exercises/{concept,practice}/*/.articles/config.json`
+- `exercises/{concept,practice}/*/.meta/config.json`
 
 ## Usage
 

building/tracks/ci/workflows.md

@@ -15,15 +15,19 @@ For information on workflows, check the following docs:
 ## Shared workflows
 
 Some workflows are shared across repositories.
-These workflows _should not be changed_.
+
+```exercism/caution
+The shared workflows are automatically synced (from the [org-wide-files repo](https://github.com/exercism/org-wide-files/)).
+You should thus not manually change their contents.
+```
 
 ### General workflows
 
 - `sync-labels.yml`: automatically syncs the repository's labels from a `labels.yml` file
 
 ### Track-specific workflows
 
-- `configlet.yml`: runs the [configlet tool](/docs/building/configlet), which checks if a track's (configuration) files are properly structured - both syntactically and semantically
+- [`configlet.yml`](/docs/building/tracks/ci/workflows/configlet): runs the [configlet tool](/docs/building/configlet), which checks if a track's (configuration) files are properly structured - both syntactically and semantically
 - `no-important-files-changed.yml`: checks if pull requests would cause all existing solutions of one or more changes exercises to be re-run
 - `test.yml`: verify the track's exercises
 

building/tracks/ci/workflows/configlet.md

@@ -0,0 +1,32 @@
+# configlet workflow
+
+The `configlet` workflow is defined in the `.github/workflows/configlet.yml` file.
+It uses the [configlet tool](/docs/building/configlet) to check if a track's (configuration) files are properly structured - both syntactically and semantically.
+It does this by running [`configlet lint`](/docs/building/configlet/lint).
+
+## Enable checking file formatting
+
+Tracks can use [`configlet fmt`](/docs/building/configlet/format) to format the track's various configuration files.
+The same command can also be used to check if all configuration files are formatted correctly.
+
+The `configlet` workflow supports verifying whether the configuration files are formatted correctly, but this is optional and disabled by default.
+To opt-into verifying configuration files' formatting, follow these steps:
+
+1. Create a `.github/org-wide-files-config.toml` file with the following contents
+
+```toml
+[configlet]
+fmt = true
+```
+
+2. After this file is merged into `main`, a PR will automatically be opened that modifies the `configlet.yml` workflow as follows:
+
+```diff
+  jobs:
+    configlet:
+      uses: exercism/github-actions/.github/workflows/configlet.yml@main
++     with:
++       fmt: true
+```
+
+3. Once this PR is merged, the `configlet` workflow will also verify the track's configuration files' formatting.

building/tracks/new/add-first-exercise.md

@@ -113,5 +113,35 @@ Tip: just can copy-paste-modify the example solution.
 Once you're done with the exercise, please add your your GitHub username to the `"authors"` array in the exercise's `.meta/config.json` file.
 This will ensure we correctly credit you with having created the exercise.
 
+### Linting
+
+To verify that the exercise is setup correctly, you can use the [configlet tool](/docs/building/configlet)'s built-in linting functionality.
+
+The first step is to fetch the `configlet` tool, for which we've created two scripts:
+
+- `bin/fetch-configlet`: run this when using \*nix or macOS
+- `bin/fetch-configlet.ps1`: run this when using Windows
+
+Running one of these scripts from the root directory of the track's repo will download the `bin/configlet` respectively `bin/configlet.exe` binary.
+
+You can then check the exercise for correctness by running [`bin/configlet lint`](/docs/building/configlet/lint).
+
+````exercism/note
+It is likely that `configlet` will report the following error:
+```shell
+The `tags` array is empty:
+/path/to/track/config.json
+```
+
+This error will be fixed in the [Prepare for launch](/docs/building/tracks/new/prepare-for-launch#h-update-metadata) step, so either:
+
+- ignore the error (for now), or
+- fix the error by adding tags
+````
+
+```exercism/note
+The [`configlet` workflow](/docs/building/tracks/ci/workflows/configlet) will automatically runs `configlet lint` whenever something is pushed to `main` or to a pull request.
+```
+
 [configlet]: /docs/building/configlet
 [canonical-data.json]: https://github.com/exercism/problem-specifications/blob/main/exercises/hello-world/canonical-data.json

building/tracks/new/setup-continuous-integration.md

@@ -8,10 +8,14 @@ Exercism repos (including track repos) use [GitHub Actions](https://docs.github.
 GitHub Actions are based on _workflows_, which define scripts to run automatically whenever a specific event occurs (e.g. pushing a commit).
 For more information on GitHub Actions workflows, check the [workflows docs](/docs/building/tracks/ci/workflows).
 
+## Pre-installed workflows
+
+Tracks come pre-installed with a number of workflows, most of which you should _not_ modify (they're called _shared workflows_).
+There is one workflow that you _should_ change though, which is the `test.yml` workflow.
+
 ## Test workflow
 
-Each track comes with a `test.yml` workflow.
-The goal of this workflow is to verify that the track's exercises are in proper shape.
+The goal of the `test.yml` workflow is to verify that the track's exercises are in proper shape.
 The workflow is setup to run automatically (in GitHub Actions terminology: is _triggered_) when a push is made to the `main` branch or to a pull request's branch.
 
 The workflow itself should not do much, except for: