From ea9284128c1d39d9bace993dcd9eace70f80ac18 Mon Sep 17 00:00:00 2001
From: manuel <charlem@sjtu.edu.cn>
Date: Sun, 28 Sep 2025 17:07:33 +0800
Subject: [PATCH] docs: intro to JOJ3 HS

---
 Readme.md    |  7 +++++++
 tt/Readme.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 Readme.md
 create mode 100644 tt/Readme.md

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..1184952
--- /dev/null
+++ b/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
+
diff --git a/tt/Readme.md b/tt/Readme.md
new file mode 100644
index 0000000..4eca50f
--- /dev/null
+++ b/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!
+