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

docs: update "How does it work?"

Browse Source
This commit is contained in:
张泊明518370910136 2024-10-05 18:10:32 -04:00
parent 0b248aad6b
commit 9165e78a16
Signed by: 张泊明518370910136
GPG Key ID: D47306D7062CDA9D
1 changed files with 27 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -63,6 +63,33 @@ pre-commit installed at .git/hooks/pre-commit
3. You only need to run steps 5, 7, and 8 in the quick start during development. If the test cases need to be updated, step 6 is also needed.
## How does it work?
These steps are executed in runner-images. We use `sudo -u tt` to elevate the permission and run `joj3` and `joint-teapot`. All the secret files should be stored in the host machine with user `tt` and mounted into the runner (e.g. `/home/tt/.config`). Since the runner uses user `student`, we can keep the data safe.
1. Run JOJ3
1. Parse the message.
- If not specified by `-msg`, it will use the git commit message from `HEAD`. The message should meet the [Conventional Commits specification](https://www.conventionalcommits.org/). We use `scope` and `description` here.
2. Find the configuration file.
- We have `conf-root` and `conf-name` specified in the CLI argument. Then the full path of configuration file is `<conf-root>/<scope>/<conf-name>`.
3. Generate stages.
- We have an empty list of stages at the beginning.
- We check all the stages from the configuration file. Stages with empty `group` field will always be added. And stages with `group = joj` will be added when `description` contains "joj" (case insensitive).
- Every stage needs to have an unique `name`, which means if two stages have the same name, only the first one will be added.
4. Run stages.
- By default, all the stages will run sequentially.
- Each stage contains a executor and a parser. Executor (currently only sandbox) executes the command and parser parses the output generated by the executor.
- The parser can return a force quit, which means all the stages after it will be skipped.
5. Generate results.
- Once the running of stages is done, it will generate a result file where the path is specified in the configuration file.
2. Run Joint-Teapot.
1. Generally speaking, it reads the JOJ3 results file and output results on Gitea.
- We use a wrapper script `joj3-teapot` to limit the commands can be run in the original `joint-teapot` for safety.
- Currently, the environment file path and joj3 result file path are hardcoded, as `/home/tt/.config/teapot/teapot.env` and `/tmp/joj3_result.json`, respectively.
2. With `joint-teapot joj3-scoreboard`, it will update the scoreboard file in grading repo.
3. With `joint-teapot joj3-failed-table`, it will update the failed table file in grading repo.
4. With `joint-teapot joj3-create-result-issue`, it create an issue in the submitter's repo to show the results.
## Models
The program parses the configuration file to run multiple stages.