Update README.md

Installation and usage documentation
Contributing

1 files changed, 117 insertions, 5 deletions

diff --git a/README.md b/README.md
index d159f42..64391db 100644
--- a/README.md
+++ b/README.md
@@ -21,13 +21,114 @@ 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.
+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] [-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, --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 <homework number>
+```
+
+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.
 
 ## Helper Checklist
 
 This section is copied from the Helper's README.md, with modifications. It
-enumerates what the Helper will grade your work upon.
+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
@@ -57,10 +158,21 @@ enumerates what the Helper will grade your work upon.
 
 This is a non-exhaustive list of Leningrade's improvement-worthy aspects.
 
-- Reliable way to obtain list of mandatory/optional files
-- Display grades in a human-friendly format
+- 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)
-- Unify criteria of redundant files
 
+
+## 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?
\ No newline at end of file