JOJ/JOJ3

Fork 0

Table of Contents

JOJ preparation and testing

Preparation

Beginning of semester
Repository templates
JOJ setup
JOJ resources

Testing process

Initial JOJ setup
New semester JOJ setup

Known issues

Gitea actions and LFS
Memory sanitizer
Test sanitizer setup

JOJ preparation and testing

Preparation

Beginning of semester

Connect to JOJ-mon using Gitea authentication
Ensure all TAs for your course have proceeded with step 1
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
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 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

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
Playground organization
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.

The first time JOJ is setup:

run extensive tests in a separate test repository
- ensure all test cases can be passed
- if different JOJ groups are available, then run them independently to ensure everything works as expected
- test on non working code, i.e. check the behavior if
  - some test cases fail
  - if the code doesn't compile
  - if the commit message is incorrect (non-conventional, wrong scope, missing footer, etc.)
when all previous tests are fine:
- create an orphan branch in course-joj with name test-repoName, where repoName corresponds to the name of the repository used by students
- the new orphan branch must have the exact same structure as the repository used by students
- switch to the new branch and follow instructions from the next section

Very important.

most of the submitted code will not get full score
ensure the setup works for both right and wrong submissions

New semester JOJ setup

Important. Never blindly reuse the setup from previous semesters.

Only release when ready:

test the setup using a separate JOJ conf-root called tt and ensure to never make it accessible to students
check the action output and ensure no WARNING is displayed, i.e. fix all warnings (the action will fail in case of ERROR in the configuration file)
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
- 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

Bug: https://github.com/actions/checkout/issues/1830#issuecomment-2314758792

Solution: adjust the YAML workflow fot checkout LFS object separately.

Sample YAML worklow file.

name: Run JOJ3 on Push
on: [push]

jobs:
  run:
    runs-on: focs-ubuntu-latest-slim
    container:
      volumes:
        - /home/tt/.config:/home/tt/.config
        - /home/tt/.cache:/home/tt/.cache
        - /home/tt/.ssh:/home/tt/.ssh
    steps:
      - name: Check out repository code
        uses: actions/checkout@focs
        with:
          lfs: false
          persist-credentials: 'true'
      - name: Checkout lfs
        run: |
          git lfs install --local
          AUTH=$(git config --local http.https://focs.ji.sjtu.edu.cn/.extraheader)
          git config --local --unset http.https://focs.ji.sjtu.edu.cn/.extraheader
          git config --local http.${{ gitea.server_url }}/${{ gitea.repository }}.git/info/lfs/objects/batch.extraheader "$AUTH"
          git lfs pull          
      - name: run joj3
        run: |
          sudo -E -u tt joj3 -conf-root /home/tt/.config/joj

Memory sanitizer

According to our current observation, MemorySanitizer with iostream linked with uninstrumented libc++ will not work. Not sure about other libraries/headers.

Explanation: https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo

Test sanitizer setup

nm -an binary | grep san