JOJ/JOJ3
25
5
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: background + global param sections

manuel 2024-10-11 18:34:28 +08:00
parent 7daeaa38ab
commit 8d59f2414b
1 changed files with 51 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
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
- assignment: eg. homework or project (no meta config needed at that level)
- repository: global repository configuration
- 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:
- required files (readme, changelog)
- git whitelist (allowed files)
- git local-whitelist (list of "self-allowed" files $\to$ use with care)
- immutable files (gitignore, workflows)
- repo size limit
**Important:** it should never be possible to disable health check.
`[files]` table: file configuration parameters:
- `whitelist.patterns [array of string]`: patterns of files allowed in the repository
- `whitelist.file [string]`: file containing student defined patterns of files. This option should not be
enabled unless strictly necessary
- `required.files [array of string]`: files that are written by students and must be found in the
repository
- `immutable.files [array of string]`: list all files managed by TT that students are forbidden to
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: