docs: intro to JOJ3 HS

Readme.md

@@ -0,0 +1,7 @@
+# JOJ3 helper scripts
+
+Collection of short shell scripts to simplify work with JOJ3. 
+
+- `admin`: scripts and configuration files used to deploy and setup JOJ3
+- `tt`: scripts used by TT to simplify routine tasks such as copying files to students repositories or collecting contribution statistics for group projects
+

tt/Readme.md

@@ -0,0 +1,49 @@
+# JOJ helper scripts for TT
+
+## `teabag.sh`
+
+This script contains simple shell recipes to *complement* [joint-teapot](https://focs.ji.sjtu.edu.cn/git/JOJ/Joint-Teapot) features. It has two main purposes: (i) copy files to students repositories and (ii) analyze contribution for group works.
+
+### Usage
+
+Run `teabag.sh -h` for detailed help. Common workflow: 
+
+1. Preparation: 
+  - run with `setup` 
+  - run with `init`
+  - use joint-teapot to generate a CSV file for groups (optional: used for contribution analysis)
+2. Copy files feature: 
+  - run with `copy` 
+  - run with `push`
+  - inform students new files were pushed and they should `pull` the changes
+3. Contribution analysis feature:
+  - run with `report`
+  - run with `contrib` (optional)
+
+Note. TT should create template repositories and only use `teabag.sh` for adjustments along the
+semester.
+
+### FAQ
+
+**Q: Why is teabag using HTTP to clone repositories instead of SSH?**
+
+A: As SJTU firewall very quickly blocks SSH requests, processing repositories (eg. cloning) is
+extremely slow. The firewall being less strict with HTTP, all repositories can be handled 
+smoothly by `teabag.sh`.
+
+**Q: I input my Jaccount password when prompted for a password but it fails, why?**
+
+A: Input your Gitea token at the password prompt.
+
+**Q: What permissions should I give to my token?**
+
+A: For security reasons, always keep permissions as minimal as possible. This script only requires 
+`write` on repository and optionally `write` on issues if using the contribution analysis feature
+to post the results in Gitea issues.
+
+**Q: I'm prompted for my token for each repository, is there a way to input it only once?**
+
+A: Yes, `man git-credential`. While you can directly add your Gitea token to `$HOME/.gitconfig`, it
+is more secure to use a *password manager* such as [pass](https://www.passwordstore.org/) to store
+your credentials. Once properly setup you will not be prompted again for your token!
+