Update Introduction to JOJ3
parent
9a7a1a0125
commit
d8b9580e33
103
Introduction-to-JOJ3.md
Normal file
103
Introduction-to-JOJ3.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
# Introduction to JOJ3
|
||||
|
||||
JOJ3 is the latest version of [JOJ Online Judge](https://focs.ji.sjtu.edu.cn/git/JOJ/JOJ3). 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](https://www.conventionalcommits.org/en/v1.0.0/) specifications. JOJ3 parses you commit and based on its content will tiger different set 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 feature
|
||||
- `fix`: the commit fix a bug
|
||||
- `docs`: the commit only contains changes related to documentation
|
||||
- `style`: the commit only adjusts the style, eg. add spaces, tabs, reformat existing code
|
||||
- `refactor`: changes to the code which neither add a feature nor fix a bug
|
||||
- `perf`: a commit which helps improving performance
|
||||
- `test`: adding or correct tests
|
||||
- `build`: changes affecting the build system, eg. Makefile, dependencies
|
||||
- `ci`: commit related to Continuous Integration (CI), eg. Gitea actions configuration
|
||||
- `chores`: changes not modifying source code or tests cases
|
||||
- `revert`: 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 the your work will be tested for correctness trhough the online judge layer of JOJ3.
|
||||
|
||||
#### Examples
|
||||
|
||||
Valid commit messages:
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Invalid commit message:
|
||||
```bash
|
||||
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.
|
||||
```bash
|
||||
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 sections briefly previews other ways to interact with and use JOJ3.
|
||||
|
||||
### Pull requests
|
||||
|
||||
JOJ3 doesn't change the way to handle (open, create, review, and approve) Pull Requests (PR). We however recommend to select 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`
|
||||
```bash
|
||||
jojsubmit() { scope=$1; shift; git commit --allow-empty -m"test($scope): joj $@" && git push; }
|
||||
alias joj-submit=jojsubmit
|
||||
```
|
||||
|
||||
Then submit to joj using
|
||||
```bash
|
||||
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 improving 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 in 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.
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
# JOJ on gitea
|
||||
|
||||
JOJ can directly be run without directly connecting to it: it suffices to commit an appropriate message to trigger testing.
|
||||
|
||||
## Basic usage
|
||||
|
||||
JOJ is triggered only when a commit message starts with `joj`. The second "parameter" of the commit message is the homework/task to be tested. If no other parameters are provided then all joj problems for that joj homework are tested. It is possible to test exercises individually by providing their number after the homework.
|
||||
|
||||
Examples.
|
||||
```bash
|
||||
git commit -m"joj. h1" # test all JOJ problems for h1
|
||||
git commit -m"feat. h1e2 completed" # no JOJ tests run
|
||||
git commit -m"joj. h1 2 5" # test h1 problems 2 and 5
|
||||
```
|
||||
|
||||
*Notes.*
|
||||
- In case you have no file to commit, run `git commit --allow-empty -m"h1"`.
|
||||
- Call JOJ on a whole assignment **only if it is complete**, otherwise only run it on the targeted exercises. Results will appear faster, and no resources will be wasted.
|
||||
|
||||
## Results
|
||||
|
||||
- To follow JOJ submission process connect to https://focs.ji.sjtu.edu.cn:2222
|
||||
- Check the issue tab of your repository: once JOJ has completed, an issue containing all the details opens
|
||||
- It displays a link to JOJ website with all the details
|
||||
- Information on the passed and failed cases
|
||||
- Links to the detail for each test case
|
||||
|
||||
## Faster submissions
|
||||
|
||||
Add the following to your `.bashrc`
|
||||
```bash
|
||||
jojsubmit() {
|
||||
git commit --allow-empty -m"joj. $@" ; git push
|
||||
}
|
||||
alias joj-submit=jojsubmit
|
||||
```
|
||||
|
||||
Then submit to joj using
|
||||
```bash
|
||||
joj-submit "p1m1 1 3"
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user