path: root/README.md

# Leningrade
Seize the Means of Deduction™

> N.B.: You will only need this tool if you are a UMJI (University of Michigan -
> SJTU Joint Institute freshman student enrolling in Manuel's VG151.

> WARNING: NO WARRANTY OF ANY KIND. THE PROJECT IS NOT REMOTELY COMPLETE.

Built on [VG101-Grade-Helper](https://github.com/BoYanZh/VG101-Grade-Helper),
to defend against VG101-Grade-Helper.

VG101-Grade-Helper ("the Helper" hereafter) helps TA's grade students' homework
submitted on [FOCS Gitea](https://focs.ji.sjtu.edu.cn/git). But the open source
nature of the Helper indicates that any UMJI student can use it. With its power,
an hgroup (homework group) may preemptively grade their homework before the TA
does, and adjust their work accordingly.

Leningrade assists this process by cutting away TA-specific features (Canvas
integration for instance), instead presenting the grades to the proletariat
student.

## Installation & Usage

First of all obviously clone or download the repo.

For non-SJTU folks who wish to take a look anyway, Leningrade is mirrored on my
self-hosted CGit instance, [CateGit](https://git.fkfd.me/leningrade.git/).

You need a decently recent version of Python 3 (tested on 3.9.7) and
dependencies listed in `requirements.txt`. To install the dependencies, run
`pip install -r requirements.txt`.

For C and C++, install [ctags](https://github.com/universal-ctags/ctags) for
code quality evaluation. Not tested yet.

Having obtained the source code, it's time to configure Leningrade. Make a copy
of `config.example.py` called `config.py`, which is where we will write our
configuration.

Here is a list of configurations you should (or might) care about:

```python
"""GENERIC"""
HGROUP_NO = 99
HGROUP_MEMBERS = [
    ("521370910996", "Vladimir Lenin"),
    ("521370910997", "Joseph Stalin"),
    ("521370910998", "Nikita Khrushchev"),
    ("521370910999", "Mikhail Gorbachev"),
]
LANGUAGE = "matlab"
```

These are self-explanatory. Note that the names do not need to match anything,
so you can make them whatever you like.

```python
MANDATORY_FILES = [f"ex{n}.m" for n in [2, 4, 5, 6]]
OPTIONAL_FILES = [f"ex{n}.m" for n in [1, 3]]
```

Of course you can do `["ex2.m", "ex4.m", ...]`. Mandatory files are generally
marked "\*" on your homework PDF. The rest are optional.

```python
"""GITEA"""
GITEA_ORG = "ENGR151-21"
GITEA_TOKEN = ""
```

`GITEA_ORG` is your organization name. Shown is its value when your repo is at
`https://focs.ji.sjtu.edu.cn/git/ENGR151-21/hgroup-<n>`.

For `GITEA_TOKEN`, obtain your token here:  
FOCS Gitea > Settings >
[Applications](https://focs.ji.sjtu.edu.cn/git/user/settings/applications) >
Generate New Token: fill in Token Name (Leningrade for example), click Generate
Token > copy the hexadecimal string on the top here.

```python
"""JOJ"""
JOJ_COURSE_ID = "vg151_fall_2021_manuel"
JOJ_SESSION_ID = ""
JOJ_HOMEWORK_ID = "615542bfb3c06a0006f45dd6"  # h2
```

Open the JOJ page where you see "Homework 2", "Homework 1" etc. At the end of
its URL you will see your `JOJ_COURSE_ID`.

`JOJ_SESSION_ID` is a bit tricky. It is a value of JOJ's cookies. When logged
in to JOJ, hit F12 (or whatever triggers DevTools) in your web browser. Switch
to Networks panel. Click on the request with type "document" or "html". See the
request header called "Cookie"? Copy whatever is behind "sid=" here. "sid" is
short for "session id", and this one we got just now is valid for 30 days. This
means you'll have to redo this once every month or so.

Open the JOJ entry for the homework you are submitting. The URL should look like
`https://joj.sjtu.edu.cn/d/vg151_fall_2021_manuel/homework/615542bfb3c06a0006f45dd6`.
Here, `615542bfb3c06a0006f45dd6` is the `JOJ_HOMEWORK_ID`.

Finally, we are ready to run Leningrade.

If you are not sure, run `python leningrade.py --help`.

```
usage: leningrade [-h] -n HOMEWORK_NUMBER [-i HOMEWORK_ID] [-I] [-G] [-J]

optional arguments:
  -h, --help            show this help message and exit
  -n HOMEWORK_NUMBER, --homework-number HOMEWORK_NUMBER
                        An integer. For h1, the value should be 1.
  -i HOMEWORK_ID, --homework-id HOMEWORK_ID
                        A hexadecimal string obtained from the JOJ URL of the homework. Can be omitted if -J is set.
  -I, --no-individual   Do not check individual submissions.
  -G, --no-group        Do not check group submission.
  -J, --no-joj          Do not upload group code to JOJ. JOJ may consume a lot of time. Set this flag if your group work has proven to pass JOJ.
```

Self-grade your homework as follows.

```
$ python leningrade.py -n 2 -i 615542bfb3c06a0006f45dd6
```

This will clone (or pull, if it already exists) your group's repo, and run tests
against it. If you have made sure your group code has passed JOJ and no further
changes have been made, you can, in your future runs, set flag `-J` to skip that
test.

Sample output:

```
Checking individual submissions...
Checking group submissions...
JOJ is now running (this may take a while)...
-> Checked: ex2.m (1/4)
-> Checked: ex4.m (2/4)
-> Checked: ex5.m (3/4)
-> Checked: ex6.m (4/4)
===== Vladimir Lenin =====
Grade: 0
good job


===== Joseph Stalin =====
Grade: -0.75
Genral Info:
individual submit missing, -0.5
individual branch untidy, -0.25

Detail:
individual branch h2/README file missing
individual branch redundant files: ex3_no_recursion.m


===== Nikita Khrushchev =====
Grade: 0
good job


===== Mikhail Gorbachev =====
Grade: 0
good job


```

## Helper Checklist

This section is copied from the Helper's README.md, with modifications. It
enumerates what the Helper will grade your work upon, i.e. rubrics.

- [x] At least two days before the group deadline, all students should
      individually complete all the mandatory tasks and push their work to their
      personal branch of their group git repository and issue a pull request.
      Students late for the individual submission must open an issue featuring: 
      (i) apologies to the reviewer,  
      (ii) clear explanations on why the work is late, and  
      (iii) a request for a new deadline fitting the reviewer.  
      The reviewer is allowed to reject the request and should set the deadline
      based on their own schedule. **(-0.5 mark)**
- [x] A student should provide feedback to at least one teammate for each
      mandatory exercise. Low quality reviews will be ignored. Each student
      should receive feedback on their individual submission. e.g. For a group
      of three: student1 → student2 → student3 → student1. **(-1 mark)**
- [x] The final group submission, done on the master branch of the group
      repository, should successfully compile or be interpreted. **(-1 mark)**
- [x] Any group submission that is more than 24 hours late will be rejected.
      **(-2.5 marks)**
- [x] For each exercise, the final submission must pass at least 25% of the test
      cases. **(-0.25 mark per exercise, up to -0.5)**
- [x] For a homework the final submission must pass at least 50% of all the test
      cases. **(-0.5 mark)**
- [x] Using global variables, breaking the rule in `code_quality.pdf`.
      **(-0.5 mark)**

## Todo & Bugs

This is a non-exhaustive list of Leningrade's improvement-worthy aspects.

- C and C++ support
- Display results as a checklist of what needs to be done
- More friendly way to specify exercises
- Reestablish USSR
- Re-enable multiprocessing for JOJ upload (#1)
- If unable to restore multiprocessing, display JOJ progress to user
- Comment worker code in a separate document (the Helper's author refused to
  comment while we want to keep mainline compatibility)
- Separate JOJ and Gitea endpoints into config

## Contributing

You may either (a) open an issue or merge request on SJTU GitLab, or (b) send a
[patch](https://git-send-email.io/) to `patch <at> fkfd <dot> me`.

Notes:
1. Please refrain from introducing too many changes to anything in `worker/`.
   Ideally, when a patch is applied to the Helper's workers, we should be able
   to apply it on ours without trouble. Please do not run a formatter (autopep8,
   black, etc.) on them either. The same goes for `util.py`, which was taken
   from the Helper.
1. Can someone please, _please_ look into #1?

## Trivia

Logo is in the public domain. Source:
[Wikimedia Commons](https://commons.wikimedia.org/wiki/File:19190501-lenin_speech_red_square.jpg)