gitea-classroom/README.md

# gitea-classroom

GitHub Classroom Ersatz für selbst-gehostete Gitea-Instanzen.  
Unterstützt **Einzel-Assignments** (ein Repo pro Student) und **Gruppen-Assignments** (ein Repo pro Gruppe mit eigenem Gitea-Team).

**Hinweis:** Dieses Tool wurde mit KI erstellt.

## Installation

```bash
pip install gitea-classroom
```

Oder lokal aus dem Quellcode:

```bash
git clone https://github.com/…/gitea-classroom
cd gitea-classroom
pip install -e .
```

## Konfiguration

```bash
export GITEA_URL="https://gitea.meine-uni.de"
export GITEA_TOKEN="dein_persönliches_api_token"
```

API-Token erstellen: Gitea → Einstellungen → Anwendungen → Token generieren  
Benötigte Scopes: `repo`, `org`, `admin:org`

---

## Template-Repo vorbereiten

Das Template-Repo muss in Gitea als Template markiert sein:  
**Repo → Einstellungen → Erweiterte Einstellungen → "Dieses Repository ist ein Template"**

Das Template kann in der eigenen Org oder bei einem anderen Nutzer liegen.  
Das Template-Repo selbst wird nie verändert.

---

## CSV-Formate

### students.csv — für Einzel-Assignments
```csv
username,name,email
max.mustermann,Max Mustermann,max@uni.de
erika.musterfrau,Erika Musterfrau,erika@uni.de
```

### groups.csv — für Gruppen-Assignments
```csv
group,username
team-a,max.mustermann
team-a,erika.musterfrau
team-b,lena.schmidt
team-b,tom.mueller
```
Gruppenname (`group`) wird Teil des Repo-Namens: `proj01-team-a`

---

## Befehle

### `add-students` — Studenten zur Organisation hinzufügen

```bash
gitea-classroom add-students --org info2-ss25 --csv students.csv
```

Fügt alle Nutzer aus der CSV dem `students`-Team der Org hinzu.  
Die Gitea-Accounts müssen vorher existieren.

---

### `create-assignment` — Einzel-Assignment erstellen

```bash
gitea-classroom create-assignment \
  --org info2-ss25 \
  --assignment ueb01 \
  --template uebung01-template \
  --csv students.csv
```

| Option | Beschreibung |
|---|---|
| `--org` | Ziel-Organisation |
| `--assignment` | Prefix für Repo-Namen (z. B. `ueb01`) |
| `--template` | Name des Template-Repos |
| `--template-owner` | Owner des Templates (Standard: `--org`) |
| `--csv` | students.csv |
| `--public` | Repos öffentlich erstellen (Standard: privat) |

Erstellt pro Student:
- Ein privates Repo (`ueb01-max.mustermann`) als Kopie des Templates
- Schreibzugriff nur auf das eigene Repo
- Einen **Feedback-PR** (`main` → `feedback`), der alle Student-Commits zeigt

```
info2-ss25/
  ueb01-max.mustermann
  ueb01-erika.musterfrau
  ...
```

---

### `create-group-assignment` — Gruppen-Assignment erstellen

```bash
gitea-classroom create-group-assignment \
  --org info2-ss25 \
  --assignment proj01 \
  --template projekt-template \
  --csv groups.csv
```

| Option | Beschreibung |
|---|---|
| `--org` | Ziel-Organisation |
| `--assignment` | Prefix für Repo-Namen (z. B. `proj01`) |
| `--template` | Name des Template-Repos |
| `--template-owner` | Owner des Templates (Standard: `--org`) |
| `--csv` | groups.csv |
| `--public` | Repos öffentlich erstellen (Standard: privat) |

Erstellt pro Gruppe:
- Ein privates Repo (`proj01-team-a`) als Kopie des Templates
- Ein Gitea-Team (`proj01-team-a`) mit Schreibzugriff für alle Gruppenmitglieder
- Einen **Feedback-PR** (`main` → `feedback`), der alle Gruppen-Commits zeigt
- Studenten sehen ausschließlich das eigene Gruppen-Repo

```
info2-ss25/
  proj01-team-a   ← max.mustermann + erika.musterfrau
  proj01-team-b   ← lena.schmidt + tom.mueller
```

---

### `list-submissions` — Abgaben einsehen (Übersicht)

```bash
gitea-classroom list-submissions --org info2-ss25 --assignment ueb01
```

Zeigt den letzten Commit je Repo in einer kompakten Tabelle.  
Funktioniert für Einzel- und Gruppen-Assignments.

---

### `list-group-submissions` — Abgaben einsehen (Detailansicht)

```bash
gitea-classroom list-group-submissions --org info2-ss25 --assignment proj01
```

Zeigt die letzten 5 Commits je Gruppen-Repo.

---

### `clone-submissions` — Abgaben lokal klonen

```bash
gitea-classroom clone-submissions \
  --org info2-ss25 \
  --assignment ueb01 \
  --dir ./abgaben
```

| Option | Beschreibung |
|---|---|
| `--org` | Organisation |
| `--assignment` | Assignment-Name |
| `--dir` | Zielverzeichnis (Standard: `.`) |

Klont alle Repos des Assignments nach `<dir>/<assignment>/<student>/`.  
Bei erneutem Aufruf wird `git pull` auf bereits geklonte Repos ausgeführt.

---

### `delete-assignment` — Assignment löschen

```bash
gitea-classroom delete-assignment --org info2-ss25 --assignment ueb01
```

Löscht alle Repos und die zugehörigen Gruppen-Teams des Assignments.  
Verlangt manuelle Bestätigung durch Eingabe des Assignment-Namens.

---

## Feedback-PR

Jedes Repo erhält automatisch einen offenen Pull Request mit dem Titel **„Feedback"**:

- **`feedback`-Branch** — eingefrorener Template-Stand (Referenzpunkt)
- **`main`-Branch** — Student-Commits werden hier gepusht
- Der PR zeigt alle Änderungen relativ zum Template und wächst mit jedem Push

Dozenten können direkt im PR Zeilen kommentieren oder ein Review hinterlassen.  
Der PR wird nie gemergt — er dient ausschließlich als Feedback-Kanal.

---

## Typischer Semesterablauf

```
Semesterbeginn:
  add-students                      (einmalig, students.csv)

Übungsblätter (Einzel):
  create-assignment   → ueb01, ueb02, ...
  list-submissions                  (Abgabe-Übersicht)
  clone-submissions                 (lokal klonen / aktualisieren)

Projekt (Gruppe):
  create-group-assignment  → proj01
  list-group-submissions            (während der Bearbeitung)
  list-submissions                  (kompakte Abgabe-Übersicht)
  clone-submissions                 (lokal klonen / aktualisieren)

Semesterende:
  delete-assignment                 (optional, für jedes Assignment)
```