From d2cf6d33dba2401fee8bbbce74be58eec5b10ba6 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Thu, 25 Mar 2021 13:27:28 +0100 Subject: [PATCH] Document .meta/config.json file for concepts --- building/configlet/lint.md | 20 +++++++++++-- building/tracks/concepts.md | 51 ++++++++++++++++++++++++++++++++-- building/tracks/config-json.md | 20 +++++-------- 3 files changed, 73 insertions(+), 18 deletions(-) diff --git a/building/configlet/lint.md b/building/configlet/lint.md index 492c0363..7d1d45ba 100644 --- a/building/configlet/lint.md +++ b/building/configlet/lint.md @@ -137,8 +137,6 @@ The `config.json` file should have the following checks: - The `"concepts[].slug"` value must be a non-empty, non-blank, lowercased string using kebab-case - The `"concepts[].name"` key is required - The `"concepts[].name"` value must be a non-empty, non-blank, titleized string -- The `"concepts[].blurb"` key is required -- The `"concepts[].blurb"` value must be a non-empty, non-blank string with length <= 350 - Each `"concepts"` value must have a `concept//about.md` file. Linting rules for this file are specified below. - Each `"concepts"` value must have a `concept//introduction.md` file. Linting rules for this file are specified below. - Each `"concepts"` value must have a `concept//links.json` file. Linting rules for this file are specified below. @@ -271,3 +269,21 @@ The `config.json` file should have the following checks: - The `"[].description"` value must be a non-empty, non-blank string - The `"[].icon_url"` property is optional - The `"[].icon_url"` value must be an URL + +### Rule: concept/<slug>/.meta/config.json is valid + +- The file must be valid JSON +- The JSON root must be an object +- The `"blurb"` key is required +- The `"blurb"` value must be a non-empty, non-blank string with length <= 350 +- The `"authors"` key is required +- The `"authors"` value must be an array +- The `"authors"` values must be non-empty, non-blank strings +- The `"authors"` values must not have duplicates +- The `"authors"` values are treated case-insensitively +- The `"contributors"` key is optional +- The `"contributors"` value must be an array +- The `"contributors"` values must be non-empty, non-blank strings +- The `"contributors"` values must not have duplicates +- The `"contributors"` values are treated case-insensitively +- Users can only be listed in either the `"authors"` or `"contributors"` array (no overlap) diff --git a/building/tracks/concepts.md b/building/tracks/concepts.md index 1c2d6b40..6f8f21ae 100644 --- a/building/tracks/concepts.md +++ b/building/tracks/concepts.md @@ -14,8 +14,7 @@ Concept metadata is defined in the `concepts` key in the [config.json file](./co { "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d", "slug": "numbers", - "name": "Numbers", - "blurb": "C# has two types of numbers: integers and floating-point numbers." + "name": "Numbers" } ] } @@ -23,17 +22,31 @@ Concept metadata is defined in the `concepts` key in the [config.json file](./co ## Files -Each concept has its own directory within the track's `concepts` directory. The name of the concept's directory must match the `slug` property of the concept, as defined in the [config.json file](./config-json.md#concept). Each concept directory must contain the following files: +Each concept has its own directory within the track's `concepts` directory. The name of the concept's directory must match the `slug` property of the concept, as defined in the [config.json file](./config-json.md#concept). + +A Concept has two types of files: + +### Documentation files + +These files are presented to the student to help explain the concept. - `about.md`: provide information about the concept for a student who has completed the corresponding concept exercise to learn from and refer back to (required) - `introduction.md`: provide a brief introduction to a student who has not yet completed the corresponding concept exercise (required) - `links.json`: provide helpful links that provide more reading or information about a concept (required) +### Metadata files + +These files are _not_ presented to the student, but used to define metadata of the concept. + +- `.meta/config.json`: contains meta information on the concept (required) + ### Example 
 concepts
 └── numbers
+    ├── .meta
+    |   └── config.json
     ├── about.md
     ├── introduction.md
     └── links.json
@@ -168,3 +181,35 @@ Links can also optionally have an `icon_url` field, which can be used to customi
   }
 ]
 ```
+
+---
+
+### File: `.meta/config.json`
+
+**Purpose:** Contains meta information on the exercise.
+
+**Presence:** Required
+
+This file contains meta information on the exercise:
+
+- `authors`: The GitHub username(s) of the exercise's author(s) (required)
+  - Including reviewers if their reviews substantially change the exercise (to the extent where it feels like "you got there together")
+- `contributors`: The GitHub username(s) of the exercise's contributor(s) (optional)
+  - Including reviewers if their reviews are meaningful/actionable/actioned.
+- `blurb`: A short description of this exercise. Its length must be <= 350. Markdown is _not_ supported (required)
+
+If someone is both an author _and_ a contributor, only list that person as an author.
+
+#### Example
+
+```json
+{
+  "authors": ["FSharpForever"],
+  "contributors": ["IWantToHelp"],
+  "blurb": "F# has two types of numbers: integers and floating-point numbers."
+}
+```
+
+Note that:
+
+- The order of authors and contributors is not significant and has no meaning.
diff --git a/building/tracks/config-json.md b/building/tracks/config-json.md
index f2502695..61d3bbdd 100644
--- a/building/tracks/config-json.md
+++ b/building/tracks/config-json.md
@@ -214,7 +214,6 @@ Each concept is an entry in the top-level `concepts` array. The following fields
 - `uuid`: a V4 UUID that uniquely identifies the concept across all tracks
 - `slug`: the concept's slug, which is a lowercased, kebab-case string. The slug must be unique across all concepts within the track
 - `name`: the concept's name
-- `blurb`: a short description of the concept. Markdown is _not_ supported.
 
 ### Example
 
@@ -224,8 +223,7 @@ Each concept is an entry in the top-level `concepts` array. The following fields
     {
       "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
       "slug": "numbers",
-      "name": "Numbers",
-      "blurb": "C# has two types of numbers: integers and floating-point numbers."
+      "name": "Numbers"
     }
   ]
 }
@@ -233,8 +231,8 @@ Each concept is an entry in the top-level `concepts` array. The following fields
 
 ## Key features
 
-The language's key features succinctly describe what the most important features of the language are. 
-They are intended to upsell the more interesting features of a language to potential students. 
+The language's key features succinctly describe what the most important features of the language are.
+They are intended to upsell the more interesting features of a language to potential students.
 Titles should strive to use as little technical jargon as possible, bearing in mind that students might not be familiar with what language-specific jargon means before learning that language.
 
 The key features are specified in the top-level `key_features` field which is defined as an array of objects with the following fields:
@@ -404,26 +402,22 @@ This is an example of what a valid `config.json` file can look like:
     {
       "uuid": "2eb4a463-355f-46ef-ac55-a75ec5afdf86",
       "slug": "basics",
-      "name": "Basics",
-      "blurb": "C# is a statically-typed language, which means that everything has a type at compile-time"
+      "name": "Basics"
     },
     {
       "uuid": "4466e33e-dcd2-4b1f-9d9d-2c4315bf5188",
       "slug": "if-statements",
-      "name": "If Statements",
-      "blurb": "An `if` statement can be used to conditionally execute code."
+      "name": "If Statements"
     },
     {
       "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
       "slug": "numbers",
-      "name": "Numbers",
-      "blurb": "C# has two types of numbers: integers and floating-point numbers."
+      "name": "Numbers"
     },
     {
       "uuid": "7a86561d-173b-45c0-a53c-1ffd7b9ff259",
       "slug": "strings",
-      "name": "Strings",
-      "blurb": "C# strings are immutable sequences of Unicode characters."
+      "name": "Strings"
     }
   ],
   "key_features": [