Version 1.0.0 (2025-02-18): Version 1.0.0

GitAdministrationAnleitung.adoc

@@ -0,0 +1,200 @@
+= 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.
+Die folgende Beispieltabelle beschränkt sich auf jene Attribute, die auch tatsächlich vom System verarbeitet
+werden.
+
+image::bilder/BilderAdministration/Admin1.png[]
+
+==== 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
+- Die *Rolle* ("Lehrer" oder nicht belegt) entscheidet über die <<Organisationen und Teams, Berechtigungen>> eines Users.
+
+Dies aus der CSV übernommenen Vor- und Nachnamen werden:
+
+* transponiert
+* Umlaute werden entfernt
+* 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 _Daten einlesen gelangen Sie nun zum Auswahldialog für den CSV - Upload:
+
+image::bilder/BilderAdministration/Admin3.png[]
+
+Wählen Sie nun Ihre CSV-Datei mit den zu erstellenden Nutzer_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 Datei 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.*
+
+=== 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[]
+