diff --git a/%5BTA%5D-JOJ-preparation-and-testing-processes.md b/%5BTA%5D-JOJ-preparation-and-testing-processes.md index db4cde0..41245c5 100644 --- a/%5BTA%5D-JOJ-preparation-and-testing-processes.md +++ b/%5BTA%5D-JOJ-preparation-and-testing-processes.md @@ -2,12 +2,107 @@ ## Preparation +### Beginning of the semester +1. Connect to [JOJ-mon](https://focs.ji.sjtu.edu.cn/joj-mon) using Gitea authentication +2. Ensure all TAs for your course have proceeded with step 1 +3. Contact Manuel on MM and send him two comments: (i) the course code and (ii) the list of **all** TAs in the course on one line, e.g. + ``` + hi, here are the TAs for ecexxx + ta1@sjtu.edu.cn ta2@sjtu.edu.cn ta3@sjtu.edu.cn + ``` + **Note.** only one TA per course needs to send this information. + +Admin will then: +- prepare a Gitea organization with imported repositories (`course-joj`, `teaching-team`, and templates, if the course has already used JOJ before) +- add all TAs to the new Gitea organization +- add all TAs to JOJ-mon + +As you get access to Gitea, check `course-joj/Readme.md` and follow instructions there. + +### Repository templates + +If no template repository exists then create one for each type of repository students will be given. At least ensure the following files are included: +- git config: `.gitignore` and `.gitattributes` (use whitelist style `.gitignore` with very strict limitations) +- gitea config: `.gitea/workflows` folder with `push.yml` and `release.yml` files +- docs: a basic `Readme.md` showing badges, explaining JOJ basic usage, and featuring a link to the [Introduction to JOJ](https://focs.ji.sjtu.edu.cn/git/JOJ/JOJ3/wiki/Introduction-to-JOJ3) +- any other files and directories that might be needed by students, e.g. make files, header files + +If template repositories exist, then review their content and see if adjustments are needed. + +Refer to [Gitea documentation](https://docs.gitea.com/usage/template-repositories) for more information on how to use templates and use variables for more personalized content. + +### JOJ setup + +All JOJ configurations is done in the `course-joj` repository: +- clone the `course-joj` repository +- add, remove, and edit files/directories in `home/tt/.config/joj` + +JOJ configuration tree structure is very flexible and many setups are possible. When preparing for assignments ensure your file organization is +- consistent over the whole course +- secure and no students can access JOJ before it is fully setup +- all tools and configurations that are reused across assignments are clearly and easily accessible in a common place (don't duplicate them in each task/assignment folder) +- a different `conf-root` can be easily setup for each repository type + + +Example. + +- a `tools` directory for all helper scripts +- a `homework` directory for the homework repository +- an `exams` directory for the exams +- a `tt` directory containing `conf-root` subdirectories used for testing purpose +- (*) marks `conf-root` used for students +- (#) marks `conf-root` used for testing purpose + +```tree +joj +├── conf.toml +├── exams +│   ├── e1 (*) +│   │   └── conf-release.toml +├── homework (*) +│   ├── conf.toml +│   ├── h0 +│   │   ├── conf-release.toml +│   │   ├── conf.toml +│   │   └── ex1 +│   │   ├── case0.in +│   │   ├── case0.out +│   │   └── conf.toml +│   ├── repo.toml +├── tools +│   ├── compile +│   ├── filelength +│   ├── strdetect +├── tt +│   ├── e1 (#) +│   │   └── conf-release.toml +│   ├── homework +│   ├── conf.toml +│   ├── h0 (#) +│   │   ├── conf-release.toml +│   │   ├── conf.toml +│   │   └── ex1 +│   │   ├── case0.in +│   │   ├── case0.out +│   │   └── conf.toml +│   ├── repo.toml +``` + +### JOJ resources + +Documentation and support: + +- [JOJ3 wiki](https://focs.ji.sjtu.edu.cn/git/JOJ/JOJ3/wiki) +- [Playground organization](https://focs.ji.sjtu.edu.cn/git/playground) +- MM JOJ team, TA channel **Important.** Never release or make JOJ available before it has been fully tested. ## Testing process +Testing is very critical. Not testing and simply assuming something works can lead to severe issues and students flooding TT with messages. + ### Initial JOJ setup If JOJ has already been used in previous semesters, you can likely skip to the next section and only refer to this section if necessary. @@ -34,17 +129,20 @@ The first time JOJ is setup: **Important.** Never blindly reuse the setup from previous semesters. Only release when ready: - - test the setup using a separate JOJ "conf-root" inaccessible to students, e.g. if students' workflow has `conf-root` setup to `projects` then test using `projects-test` - - if an assignment has several tasks, don't release them one by one - - release a whole assignment at once + - test the setup using a separate JOJ `conf-root` called `tt` and ensure to never make it accessible to students + - if an assignment has several tasks, ensure all of them work well before releasing to students + - release a whole assignment at once, don't release task by task Always ensure to test before releasing to students: - switch to the corresponding branch on `course-joj` - push an empty commit message `test(task): new semester setup [all]` - check the issue and ensure everything works as expected - - in case of problem refer to the above "Initial JOJ setup" section and run further tests in another repository - - + - in case of problem + - check if the software version has changed since last offering + - refer to the above "Initial JOJ setup" section and run further tests in another repository + - either fix `course-joj` sample code or regenerate `case.out` files + - if fixing the the code, ensure the fix doesn't break any rule specific to the task + ## Known issues ### Gitea actions and LFS