Document .meta/config.json file for concepts (#96)

Author: ErikSchierboom

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/<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.
@@ -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/&lt;slug&gt;/.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)

building/tracks/concepts.md

@@ -14,26 +14,39 @@ 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"
     }
   ]
 }
 ```
 
 ## 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
 
 <pre>
 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.

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,17 +223,16 @@ 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"
     }
   ]
 }
 ```
 
 ## 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": [