= Anleitung zur Administration und Verwendung einer _gitcamp_ - Schulinstanz
:author: Thomas Niesenhaus <thomas.niesenhaus@zsl-rska.de>
include::kapitel-settings.adoc[]

== Wichtige Begriffe und Rollen
Dieses Dokument soll als Schritt-für-Schritt-Anleitung zum Einrichten, Verwalten und Verwenden einer _gitcamp_-Instanz an Ihrer
Schule dienen. Zum besseren Verständnis werden im Folgenden häufig verwendete Begriffe und Nutzerrollen
spezifiziert.


* **Repository ("Repo")**: Der Ort, an dem Sie Ihren Code/ Ihre Dateien für ein Projekt einschließlich ihres
Revisionsverlaufs speichern.
* **Organisation**: Gruppe von Nutzern mit Zugriff auf gemeinsame Repos -> Klasse oder Kurs
* **Team**: Eine Organisation kann aus mehreren Teams mit unterschiedlichen Zugriffsrechten bestehen
(normalerweise: "owners" und "students")
* **Schulverwalter_in**: Zuständig für die Schulinstanz. Kann als einzige Person neue Nutzer (Lehrer_innen oder Schüler_innen)
anlegen, löschen, Passwörter zurücksetzen etc.
* **Lehrerinnen und Lehrer**: Können neue Organisationen (Klassen) mit Teams und Organisations-Repos anlegen.
* **Schülerinnen und Schüler**: Können eigene Repos anlegen, aber keine Organisationen (Klassen)
oder Teams

== Administration der _gitcamp_-Instanz

=== Nutzer_innen anlegen

Das Anlegen von Nutzerinnen und Nutzern geschieht grundsätzlich durch Hochladen von ASV-Daten im CSV - Format.
Im folgenden sehen Sie eine Beispieltabelle für Lehrkräfte.

image::bilder/BilderAdministration/Admin1.png[]

Und hier die entsprechende CSV-Datei als plain text:

----
"Gruppen";"Vornamen";"Nachname";"ID";"E-Mail"
"7a";"Peter";"Muster";"43443fg-45354";"peter@muster.de"
"7a, IMP8";"Ute";"Fischer";"43443fg-45354";"ute@fischer.de"
"8b";"Lena";"Schmidt";"23432ab-98765";"lena@schmidt.de"
"9c";"Jonas";"Meier";"56474cd-34678";"jonas@meier.de"
"10a";"Sophie";"Keller";"76453ef-12345";"sophie@keller.de"
"IMP8";"Max";"Bauer";"98345gh-56789";"max@bauer.de"
"7b, 9c";"Laura";"Wagner";"34567ij-23456";"laura@wagner.de"
----

Die Schüler-CSV sieht im Grunde genau so aus. Lediglich das Attribut _Gruppen_ wird zu _Klasse_. Auf der Seite
des Upload-Dialogs (s.u.) sind entsprechende Vorlagen hinterlegt.

==== Verarbeitung der Daten

Diese Tabelle würde nach dem Upload als CSV-Datei folgendermaßen verarbeitet werden:

- *Vor- und Nachname* wird importiert, aus _Vorname.Nachname_ wird der Username gebildet
- Die *Emailadresse* wird entsprechend zugeordnet, falls vorhanden, ansonsten Vergabe einer Platzhalteradresse
- *Klassen* - Zuordnung wird importiert, es werden automatisch entsprechende Klassen (Organisationen) mit Lehrern und Schülern
gebildet


Dies aus der CSV übernommenen Vor- und Nachnamen werden:

* transponiert
* Umlaute werden transponiert (ä -> ae usw.)
* doppelte Vornamen werden entfernt. Z.B.: aus "Ben Marlon MüllerHofholz" wird
"Ben.MuellerHofholz"
* Der Benutzer jedes Nutzers Users wird nach folgendem Schema
erzeugt: Vorname.Nachname
* Bei identischen Vornamen, Nachnamen und/oder Geburtsnamen jedoch unterschiedlicher ID
wird an den generierten Nutzernamen eine fortlaufende Nummer angehängt.

Beim Import von Nutzern aus der CSV-Datei werden diese bereits in die richtigen Klassen (Organisationen) eingepflegt.
Nutzer, die sowohl in der CSV, als auch in der DB vorhanden sind, werden bei Bedarf neuen Klassen (Neues Schuljahr) oder
zusätzlichen Organisationen (zB neue Lerngruppe) zugeordnet. Vorhandene Nutzer (DB + CSV) werden aus allen, nicht in der
CSV zu diesem jeweiligen Nutzer hinterlegten Klassen gelöscht.

==== CSV - Upload

Klicken Sie auf den Button _Benutzerverwaltung_ (oben rechts). Sie gelangen zur Übersichtsseite der Schulverwalter-Funktionen.

image::bilder/BilderAdministration/Admin2.png[]

Über _Zum CSV-Upload_ gelangen Sie nun zum Auswahldialog für den CSV - Upload:

image::bilder/BilderAdministration/Admin3.png[]

Wählen Sie nun jeweils Ihre CSV-Datei mit den zu erstellenden Lehrer_innen und Schüler_innen aus. Bei erfolgreicher Verarbeitung Ihrer Datei, erhalten
Sie nach wenigen Sekunden eine Übersicht über alle importierten Schüler_innen und Lehrer_innen.

*Achtung: Die CSV Dateien wird nur mit ";" als Trennzeichen erkannt und verarbeitet. Manche Tabellenkalkulationen speichern
standardmäßig mit ",". Im Zweifelsfall entsprechende Einstellungen vornehmen bzw. die Datei im einfachen Texteditor öffnen
und bearbeiten. Bitte im utf-8 Format abspeichern und alle Texte in der Datei in Hochkommas setzen.*

=== Passwörter
==== Initialpasswort
Beim Import wird automatisch ein Initialpasswort generiert, welches bei der ersten Anmeldung
geändert werden muss. Die Lehrkraft erhält per E-Mail eine Liste mit den Nutzerdaten der
Klasse(n) in denen sie unterrichtet. Außerdem wird die Passwortliste unmittelbar nach dem Upload angezeigt. Es wird empfohlen,
an dieser Stelle direkt einen Screenshot zu erstellen, da der Versand per Mail Stand 10/2024 nicht immer zuverlässig
funktioniert hat.

==== Passwortreset
Der Controller spielt je nach Lehrkraft die von ihr unterrichteten Klassen (Organisationen) in der
GUI aus. Nach Auswahl der Klasse (Organisation) zeigt der Controller die Schülerinnen und
Schüler der Klasse (Organisation) an. Nun kann die Lehrkraft in der jeweiligen Spalte der
Schülerin oder des Schülers den Button „Passwort zurücksetzen“ anklicken. Anschließend wird
der Lehrkraft ein temporäres Passwort angezeigt, welches bei der nächsten Anmeldung geändert
werden muss.

=== Weitere Infos

Weitere technische Informationen z.B. zu Löschroutinen und User-Quotas gibt es hier:
xref:GitAdministrationKurzdokumentation.adoc[Kurzdokumentation IBBW].



== Organisationen und Teams

Die _Organisation_ ist ein zentrales Element der _gitcamp_-Umgebung. Sie stellt eine Gruppe von Usern mit Zugriff
zu gemeinsamen Repositories dar. Im Schulumfeld werden Organisationen verwendet um z.B. Klassen, Kurse und
AG's abzubilden. Eine Organisation besteht aus mindestens einem _Team_. Das sind Untergruppen von Usern mit
genau spezifizierten Zugriffs- und Erstellungsrechten innerhalb der Organisation. Nur Lehrer_innen dürfen Organisationen
und Teams erstellen. Ob Schüler_innen Organisations-Repositories erstellen dürfen, lässt sich in den Team-Einstellungen
spezifizieren. Standardmäßig ist dies nicht der Fall.

Im Folgenden zeigt Ihnen die fiktive Nutzerin "Lilo Wagner" (Rolle: Lehrerin) schrittweise das Erstellen und Verwalten
einer Organisation. Bitte beachten Sie, dass eine Organisation für Ihre Klasse / Ihren Kurs u.U. schon automatisch durch
den Schulverwalter im Zuge des CSV-Uploads erstellt wurde (siehe oben).

Wählen Sie über den "+"-Button oben rechts "Neue Organisation".

image::bilder/BilderAdministration/Orgas1.png[]

Wählen Sie einen geeigneten Namen für Ihre Organisation.

image::bilder/BilderAdministration/Orgas2.png[]

Die Sichtbarkeit Ihrer Organisation sollte in der Regel "begrenzt" (jeder eingeloggte User, also praktisch "schulweit")
oder "privat" (nur für Orga-Mitglieder) sein. Nach der Erstellung sollte sich die Ansicht verändert haben. Wie links
oben zu sehen, befinden wir uns nun in der Organisationsansicht. Über den kleinen Pfeil können Sie die Ansicht jederzeit
zwischen allen Organisationen und Ihrer User-Ansicht wechseln.

image::bilder/BilderAdministration/Orgas3.png[]

Mit dem Button oben rechts gelangen Sie nun in die Detailansicht der Organisation:

image::bilder/BilderAdministration/Orgas4.png[]

Im folgenden Screenshot wurde der "Teams"-Tab ausgewählt. Erstellt man, eine Organisation, wird automatisch ein Team
namens "Owners" erzeugt mit dem Erstellenden als einzigem Mitglied. Bei einer vom Schulverwalter per CSV_Upload automatisch
erstellten Organisation gibt es im Normalfall außerdem bereits ein Team namens "Students" mit den entsprechend Schüler_innen.

image::bilder/BilderAdministration/Orgas5.png[]

Über den Button "Neues Team" kann man manuell ein weiteres Team erstellen. Dabei lassen sich umfangreiche Einstellungen bzgl.
der Berechtigungen der Teammitglieder vornehmen. Diese sind gut beschrieben und sollten daher selbsterklärend sein. Ansonsten
verweisen wir auf den entsprechenden Abschnitt der offiziellen Codeberg-Dokumentation: https://docs.codeberg.org/collaborating/create-organization/#teams .

Über _Ansehen_ -> _Einstellungen_ ändern Sie diese Berechtigungen für ein bereits bestehendes Team. Dort können Sie das
betreffende Team bei Bedarf auch löschen.

Zum Abschluss fügen wir dem neu erstellten Team noch zwei Mitglieder hinzu. Auf der Organisationsseite gelangen wir beim neu
erstellten Team "Schueler" über _ansehen_ auf folgender Seite:

image::bilder/BilderAdministration/Orgas6.png[]

Über das Textfeld werden nach Eingabe von mindestens zwei Zeichen entsprechende User vorgeschlagen, die man nun dem Team
hinzufügen kann. Dabei findet man nur User, die unter _Einstellungen -> Profil_ die Benutzersichtbarkeit auf
"öffentlich" geändert haben. Dazu klickt man zunächst auf den eigenen Avatar ganz oben rechts.

== Repositories

In den Repositories liegen Ihre Daten, also z.B. Ihr Quellcode oder Ihre Dokumentation. Dort geschieht auch die
Versionsverwaltung für Ihr Projekt. Grundsätzlich gibt es zwei Arten von Repositories:

- Repos für persönliche Projekte
- Repos für Organisations-Projekte

Ein persönliches Projekt wäre z.B. ein Tool, das eine Informatiklehrkraft entwickeln möchte oder ein Programmierprojekt eines
Kursteilnehmenden. Organisationsrepos stellen beispielweise einer Klasse Programmier-Vorlagen samt Dokumentation zur Verfügung
oder beinhalten gemeinsame Projektarbeiten von Teams aus Schüler_innen.

So erstellen Sie ein neues Repository:

image::bilder/BilderAdministration/Orgas7.png[]

Dabei öffnet sich diese Seite:

image::bilder/BilderAdministration/Orgas8.png[]

Es gibt noch weitere Einstellungen, die im Normalfall nicht geändert werden müssen. Falls doch, sei erneut auf die offizielle
Dokumentation verwiesen: https://forgejo.org/docs/latest/user/first-repository/ . _Besitzer_ kann entweder der User selbst
oder eine Organisation sein. So erstellt man entweder ein privates oder ein Organisationsrepo.

image::bilder/BilderAdministration/Orgas9.png[]

Die folgende Seite zeigt nun ein leeres Repository und enthält den Link auf das selbige zur weiterverwendung in
der Konsole oder einem sonstigen git-fähigen Tool. Außerdem steht ein Anleitung zur Verfügung, mit der man entweder ein
neues oder ein bestehendes lokales Repository verknüpfen kann.

Man kann auch im _gitcamp_ selbst neue Dateien erstellen und zu einem Repository hinzufügen. Auch wenn diese Funktion
voraussichtlich eher selten zum Einsatz kommen wird, zeigen wir sie zum Abschluss kurz, um einen Blick auf die Versionshistorie
einer Datei werfen zu können.

Wir klicken auf _Neue Datei_ und füllen dann folgendermaßen aus:

image::bilder/BilderAdministration/Orgas10.png[]

Bestätigen wir nun weiter unten mit _Änderungen committen_, haben wir die erste Datei unseres Repos erstellt. Klicken Sie
nun auf das Stift-Symbol, um die Datei zu ändern und fügen sie einen weiteren Satz hinzu. Nach erneutem _Commit_ sollte
das Ganze in etwa so aussehen:

image::bilder/BilderAdministration/Orgas11.png[]

Klickt man nun auf die zweite, geänderte Version (oben), erhält man detaillierte Informationen, über die Änderungen im
Vergleich zur Vorversion:

image::bilder/BilderAdministration/Orgas12.png[]

