Document tags field

building/config.json

@@ -717,6 +717,13 @@
     "title": "The Analyzer Interface",
     "blurb": ""
   },
+  {
+    "uuid": "4dec2835-6dc0-493b-81aa-d93cf1d6036c",
+    "slug": "tooling/analyzers/tags",
+    "path": "building/tooling/analyzers/tags.md",
+    "title": "Tagging solutions",
+    "blurb": ""
+  },
   {
     "uuid": "fd89f1aa-e73b-46f0-9759-da5cc9969069",
     "slug": "tooling/representers",

building/configlet/lint.md

@@ -185,6 +185,19 @@ The `config.json` file should have the following checks:
 - The `"concepts[].slug"` value must be a kebab-case string² with length <= 255
 - The `"concepts[].name"` key is required
 - The `"concepts[].name"` value must be a Title Case string³ with length <= 255
+- The `"concepts[].tags"` key is optional
+- The `"concepts[].tags.all"` key is optional, unless `"concepts[].tags.any"` is empty
+- The `"concepts[].tags.all"` value must be an array
+- The `"concepts[].tags.all"` values must be non-blank tag⁷ strings with length <= 255
+- The `"concepts[].tags.all"` values must not have duplicates
+- The `"concepts[].tags.any"` key is optional, unless `"concepts[].tags.all"` is empty
+- The `"concepts[].tags.any"` value must be an array
+- The `"concepts[].tags.any"` values must be non-blank tag⁷ strings with length <= 255
+- The `"concepts[].tags.any"` values must not have duplicates
+- The `"concepts[].tags.not"` key is optional
+- The `"concepts[].tags.not"` value must be an array
+- The `"concepts[].tags.not"` values must be non-blank tag⁷ strings with length <= 255
+- The `"concepts[].tags.not"` values must not have duplicates
 - Each `"concepts"` value must have a `concept/<concepts.slug>/about.md` file. Linting rules for this file are specified below.
 - Each `"concepts"` value must have a `concept/<concepts.slug>/introduction.md` file. Linting rules for this file are specified below.
 - Each `"concepts"` value must have a `concept/<concepts.slug>/links.json` file. Linting rules for this file are specified below.
@@ -372,6 +385,19 @@ The `config.json` file should have the following checks:
 - The `"approaches[].contributors"` values must not have duplicates
 - The `"approaches[].contributors"` values are treated case-insensitively
 - Users can only be listed in either the `"approaches[].authors"` or `"approaches[].contributors"` array (no overlap)
+- The `"approaches[].tags"` key is optional
+- The `"approaches[].tags.all"` key is optional, unless `"approaches[].tags.any"` is empty
+- The `"approaches[].tags.all"` value must be an array
+- The `"approaches[].tags.all"` values must be non-blank tag⁷ strings with length <= 255
+- The `"approaches[].tags.all"` values must not have duplicates
+- The `"approaches[].tags.any"` key is optional, unless `"approaches[].tags.all"` is empty
+- The `"approaches[].tags.any"` value must be an array
+- The `"approaches[].tags.any"` values must be non-blank tag⁷ strings with length <= 255
+- The `"approaches[].tags.any"` values must not have duplicates
+- The `"approaches[].tags.not"` key is optional
+- The `"approaches[].tags.not"` value must be an array
+- The `"approaches[].tags.not"` values must be non-blank tag⁷ strings with length <= 255
+- The `"approaches[].tags.not"` values must not have duplicates
 
 ### Rule: exercises/{concept|practice}/&lt;slug&gt;/.approaches/&lt;approach-slug&gt;/content.md is valid
 
@@ -564,3 +590,13 @@ The `config.json` file should have the following checks:
    ```
 
    You can run `configlet uuid` to generate a suitable UUID.
+
+7. **Valid analyzer `tag`**: A non-blank string¹ that is formatted as `<category>:<thing>`.
+   The `<category>` value must be one of:
+
+- `paradigm` (e.g. `paradigm:functional`)
+- `technique` (e.g. `technique:recursion`)
+- `construct` (e.g. `construct:bitwise-and`)
+- `uses` (e.g. `uses:DateTime.add_seconds`)
+
+The `<thing>` value must a string that contains only characters in the range `[a-z0-9]`, optionally separated by dashes (e.g. `"two-fer"`) or underscores (e.g. `"two_fer"`). It must match the regular expression: `^[a-z0-9]+([-_][a-z0-9]+)*$`

building/tooling/analyzers/README.md

@@ -19,3 +19,4 @@ You can use the following documents to learn more about building an analyzer:
 - [The Analyzer interface.](/docs/building/tooling/analyzers/interface)
 - [How to build a Docker image with Docker for local testing and deployment](/docs/building/tooling/analyzers/docker)
 - [Writing Analyzer comments](/docs/building/tooling/analyzers/comments)
+- [Tagging solutions](/docs/building/tooling/analyzers/tags)

building/tooling/analyzers/interface.md

@@ -38,6 +38,12 @@ The `analysis.json` file should be structured as followed:
       "comment": "ruby.general.some_unparameterised_message"
     },
     "ruby.general.some_unparameterised_message"
+  ],
+  "tags": [
+    "construct:list",
+    "paradigm:functional",
+    "technique:higher-order-functions",
+    "uses:List.unfold"
   ]
 }
 ```
@@ -79,6 +85,22 @@ Comments without a type field default to `informative `.
 Currently in the website, we soft-block on `essential` comments, encourage students to complete `actionable` comments before marking as complete on Practice Exercises (but not Concept Exercises), but don't suggest any action on `informative` or `celebratory`.
 However, in the future we may choose to add emojis or indicators to other types, or group them separately.
 
+### `tags` (optional)
+
+The `tags` field is an array of strings.
+Each tag is formatted as: `"<category>:<thing>"`.
+
+Some examples being:
+
+- `"paradigm:functional"`
+- `"technique:recursion"`
+- `"construct:bitwise-and"`
+- `"uses:DateTime.add_seconds"`
+
+Tags can be used to identify what constructs/techniques/paradigms a solution uses.
+
+For more information, see [Tagging solutions][tagging-solutions].
+
 ## Debugging
 
 The contents of `stdout` and `stderr` from each run will be persisted into files that can be viewed later.
@@ -87,3 +109,4 @@ You may write an `analysis.out` file that contains debugging information you wan
 
 [website-copy-repo]: https://github.com/exercise/website-copy
 [writing-analyzer-comments]: /docs/building/tooling/analyzers/comments
+[tagging-solutions]: /docs/building/tooling/analyzers/tags