This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Introduction to JOJ3
JOJ3 is the latest version of JOJ Online Judge. As it now fully integrates with Gitea, testing your code is as simple as a push!
Simplified JOJ3 structure
JOJ3 takes advantage of the latest technologies in order to secure and simplify your workflow. It is composed of three main layers:
- Heath-check: ensures your repository is healthy, eg. commit messages follow common industry standards, no unexpected files are pushed, etc.
- Runners and online judge: test the quality and correctness of the submitted work
- Teapot: format all the feedback and post an issue in your repository
Basic usage
On every single push, heath-check is run, while other layers are activated based on the needs defined by the Teaching Team (TT) and your commit message. At the user level, there is nothing to configure or do aside of using a proper commit message.
Commit messages
All commit messages are expected to comply with conventional commits specifications. JOJ3 parses your commit message and based on its content will trigger different sets of actions. Any commit must be in the format
type(scope): message
Conventional commits format cheat-sheet
The type must be one of
feat: the commit adds a new featurefix: the commit fixes a bugdocs: the commit only contains changes related to documentationstyle: the commit only adjusts the style, eg. add spaces, tabs, reformat existing coderefactor: changes to the code which neither add a feature nor fix a bugperf: a commit which helps improve performancetest: adding or correcting testsbuild: changes affecting the build system, eg. Makefile, dependenciesci: commit related to Continuous Integration (CI), eg. Gitea actions configurationchores: changes not modifying source code or test casesrevert: revert a previous commit
The scope is defined and provided by TT for each task or each assignment. For instance, it could be hw2/ex4 for homework 2 exercise 4 or p1/m3 for project 1 milestone 3. If you are unsure of the scope of a task reaching to TT.
The message should concisely describe the changes included in this commit. If message contains the keyword joj then your work will be tested for correctness through the online judge layer of JOJ3.
Examples
Valid commit messages:
git commit -m"feat(h1/e2): skeleton" # no online-judge
git commit -m"fix(h1/e2): allocate memory before using it" # no online-judge
git commit -m"feat(h1e2): joj task completed" # run online-judge
git commit -m"fix(h1/e2): joj fix for test-case 3" # run online-judge
git commit -m"test(h1/e2): joj ensure all test-cases passed" # run online-judge
git commit -m"docs(h1): student ids added" # no online-judge
Invalid commit message:
git commit -m"" # message missing
git commit -m"my 1st commit message" # not following conventional commit format
git commit -m"feat: skeleton" # missing scope
git commit -m"joj(h1/e2): test" # wrong format, joj is not a valid type
git commit -m" 增加 ex2.c" # never commit with non-ascii characters in your message
git commit -m"feat(h1/e2)： skeleton" # not a regular : symbol
If at any stage you push with an invalid commit you can easily fix it be pushing an empty commit, eg.
git commit --allow-empty -m"chore(h1/e2): override wrong commit"
git push
Results
Once you have pushed your work connect to Gitea and check the issue tab for all the feedback on your submission.
More advanced usage
This section briefly previews other ways to interact with and use JOJ3.
Actions
From the top of JOJ feedback issue you can click the Gitea Actions #xxx link to directly jump to the logs of the corresponding running action. This is especially useful if something failed and you want more insight on what happened. All run actions can be accessed by clicking the Actions tab.
Pull requests
JOJ3 doesn't change the way to handle (open, create, review, and approve) Pull Requests (PR). We however recommend selecting the option Create squash commit. Then make sure to set the commit message to a meaningful string, eg. feat(h1): ready for submission, and click Clear squash commit. Finally, click again on Create squash commit to complete the PR.
Faster submissions
Add the following to your .bashrc
jojsubmit() { scope=$1; shift; git commit --allow-empty -m"test($scope): joj $@" && git push; }
alias joj-submit=jojsubmit
Then submit to joj using
joj-submit h2/e5 # creates and pushes commit test(h2/5): joj
joj-submit h2/e5 more tests # creates and pushes commit test(h2/e5): joj more tests
Contributing
JOJ3 is still in heavy development and needs your help! You can contribute in two main ways:
- Provide feedback on your experience using JOJ3 and help improve it: contact your TT who will get in touch with JOJ3 developers
- Join JOJ3 development team: contact Manuel or Boming on Mattermost
The core part of JOJ3 is written in Go while Joint-Teapot part is coded in Python. While the software in itself is very advanced, its architecture is not only very simple, making JOJ3 easily accessible even to motivated freshmen, but also very flexible thereby allowing modular development. The most important requirements to join the development teams are a strong motivation to learn more, the ability to work as part of an international team of developers, as well as the ability to accept and follow directions.