docs: background + global param sections

JOJ3-Configuration-Schema.md

@@ -1,17 +1,31 @@
-# Config file specs for TT
+# JOJ3 configuration documentation for TAs
 
-*Goals:* simple configuration files, which can easily be manually edited by TAs.  These files are then parsed by joj-config-generation script to generate final internal `json` configurations files and joj3 to find the `json` config files.
+*Goals:* simple configuration files, which can easily be manually edited by TAs.  These files are then parsed by `joj-config-generation` script to generate final internal `json` configurations files used by JOJ3.
 
 Levels:
-- repository: global repository config 
+- repository: global repository configuration 
-- assignment: eg. homework or project (no meta config needed at that level)
+- assignment: eg. homework or project
 - task: eg. exercise or milestone
 
-JOJ configuration generator should read both repository and task `.toml` files and generate a single `conf.json` file located in the folder of the corresponding task.
+## Background 
 
-## Commit message and course-joj repo tree 
+Brief introduction to the structure of JOJ configuration and how it impacts students' submissions.
 
-Commit messages must follow conventional commits format: `type(scope): message`.  We use `scope` to track the exact task which is being worked on.
+### Configuration repository
+
+All configuration is done through a `course-joj` repository. TAs connect to the repository, read the
+`Readme.md`, and follow instructions to setup JOJ3 for a course. If previous TAs have already
+prepared JOJ3, then only testing is required. Otherwise more setup is required. 
+
+The repository follow the server structure, so that deploying is can done easily using s simple
+script. To find JOJ configuration files go to `home/tt/.config/joj`. Each folder should correspond
+to a different assignment. This is where `.toml` files will have to be pushed in order to generate
+the corresponding JOJ3 `conf.json` files.
+
+
+### Commit messages
+
+When using JOJ3, Commit messages must follow conventional commits format: `type(scope): message`, where `scope` is used to track the exact task which is being worked on.
 
 Basic rules:
 - health check is **always** run first
@@ -19,39 +33,56 @@ Basic rules:
 - JOJ is only triggered if `joj` appears in `message`
 
 Scope usage:
-- `scope` must match joj config tree (`home/tt/.config/joj` subtree in `course-joj` repo), eg. if tree is `h1/ex2` the `scope` must be `h1/ex2`, if tree is `hw4/1` then scope is also `hw4/1`.
+- `scope` must match JOJ configuration tree (`home/tt/.config/joj` subtree in `course-joj` repo), eg. if tree is `h1/ex2` the `scope` must be `h1/ex2`, if tree is `hw4/1` then scope is also `hw4/1`.
 - if a scope is invalid then return a warning containing the list of valid scopes and exit nicely (either this is a typo, or this an exercise that do not require coding)
 - as health check must always be run, `scope` should be checked after it
 
+Refer to [Introduction to JOJ3](/Introduction-to-JOJ3.md) for more details.
 
 
 ## Repository level configuration
 
-Teaching team info, eg. useful to check who triggered a grading.
+The first and most simple file to write is `repo.toml`. The template below can be used as a starter.
+It contains the part of the configuration that will be used globally for all assignments and tasks.
 
+`[repo]` table: general configuration parameters
+- `max_size [int]`: maximum size allowed for a repo in MB 
+- `owners [array of string]`: TT members' jaccount
 
-Health check configuration:
+`[files]` table: file configuration parameters:
-- required files (readme, changelog)
+- `whitelist.patterns [array of string]`: patterns of files allowed in the repository
-- git whitelist (allowed files)
+- `whitelist.file [string]`: file containing student defined patterns of files. This option should not be
-- git local-whitelist (list of "self-allowed" files $\to$ use with care)
+ enabled unless strictly necessary 
-- immutable files (gitignore, workflows)
+- `required.files [array of string]`: files that are written by students and must be found in the
-- repo size limit
+ repository
-
+- `immutable.files [array of string]`: list all files managed by TT that students are forbidden to
-**Important:** it should never be possible to disable health check.
+ modify
+- `whitelist.file [string]`: sha26sum of all immutable files
 
+**Important:** 
+- it should never be possible to disable health check
+- make `whitelist.patterns` **very strict** or students will push random files
+- unless you have no way to set or predict students' filename, do not use `whitelist.file`
 
+<details><summary>Sample `repo.toml`</summary>
 ```toml
+# repo section
+# generic global parameters for the whole repo 
 [repo]
-owners = ["mac-wang", "jon-lee", "allen_wr"] # teaching team
+owners = ["mac-wang", "jon-lee", "allen_wr"] # jaccounts
 max_size = 5 # repo max size in MB
 
+# files section
+# file related global parameters for the whole repo
 [files]
 whitelist.patterns = ["*.cpp", "*.c", "*.m", "*.md", "Makefile", "CMakelist.txt", ".gitea", "messenger.json"] # files/patterns which are not  forbidden
-whitelist.file = "messenger.json" # IMPORTANT: only use if strictly necessary. Almost no course should enable this option
 immutable.files = [".gitignore", ".gitattributes", ".gitea/workflows/push.yaml"] # readonly files
-immutable.hash = ["fafssafds7","kjklhk5hk345", "nvnfjuysf653214"] # hash of readonly files
+immutable.hash = "26a7c6e8af3a562feef511898321ac206bed26cca50b4bd5ca6e72dec776d86b" # hash of readonly files
+required.files = [ "Changelog.md", "Readme.md" ]
 ```
 
+</details>
+
 ## Task level configuration
 
 Basic idea: