[ORGA] Repo als Single Source of Truth

[cagix]

vgl. https://github.com/kaist-cp/cs420/labels/announcement

Alle Unterlagen werden direkt im Repo bereitgestellt (#559), Kommunikation erfolgt über Tickets ("Announcement"), Aufgaben werden als Ticket gestellt, Abgabe per PR (in Code-Repos).

Repo-Strukturen: Lecture-Repo mit Orga, Unterlagen, Aufgaben/Tickets plus Dungeon-Repo mit Code-Vorgabe (vgl. #345).

---

Edit:

Aktuell haben wir je ein:

• Lecture-Repo mit
  • Orga-Kram (ändert sich jedes Semester)
  • Vorlesungungsinhalten: Skript+Folien (Markdown), Code-Beispiele (Java, ...)
  • Aufgaben fürs Praktikum (Markdown)
• Vorgabe-Repo mit dem Vorgabe-Code (Java) für die Konzept-Aufgaben
• Musterlösungs-Repo (intern) mit Aufgabe+Vorgabe+Lösung
• Desktop-Repo mit Starter-Code für die Dungeon-Aufgaben
• Musterlösungs-Repo (intern) mit Beispiel-Dungeon
• Quizzes-Repo (intern)
• Semester-Repo mit Git-Subtrees für Vorgabe-Repo und Desktop-Repo, plus Diskussionsforum

Die Aufteilung ist "historisch gewachsen", und am Anfang stand die Idee einer in sich geschlossenen Kurs-Webseite.

• Prüfen, ob die Quizzes ins Lecture-Repo integriert werden könnten und/oder sogar in das Vorlesungsmaterial eingebaut werden können ([Tooling] Quizzes direkt im Skript? #332)
• Prüfen, ob die Vorgaben ins Lecture-Repo integriert werden könnten (Vor-/Nachteile? Strukturen?) oder besser in einem eigenen Repo bleiben (dann Aufgaben plus Vorgaben plus Desktop-Dungeon-Starter)
• Prüfen, ob eine andere+einfachere Aufteilung sinnvoll ist:

  • Variante A (Vorlesung/Aufgaben):

    Gemeinsames Repo für Vorlesungsinhalte (Markdown, Slides, Skript/Web, Code-Beispiele, Quizzes) und Aufgaben plus Vorgaben (Markdown, Code-Vorgaben, Desktop als Dungeon-Starter)

    vs.

    Lecture-Repo für Vorlesungsinhalte (Markdown, Slides, Skript/Web, Code-Beispiele, Quizzes), und ein separates Repo für Aufgaben plus Vorgaben (Markdown, Code-Vorgaben, Desktop als Dungeon-Starter)

  • Variante B (Lösungen):

    Gemeinsames (internes) Repo für Lösungen zu Konzeptaufgaben und Dungeon-Aufgaben
    vs.
    Musterlösungs-Repo (intern) für Musterlösung, und ein separates Musterlösungs-Repo (intern) mit Beispiel-Dungeon
    entschieden in https://github.com/PM-Dungeon/Homework-Solutions/pull/24#issuecomment-1105123341

  • Variante C (Vorgaben):

    **Gemeinsames Repo für die Vorgaben (Konzeptaufgaben, Dungeon-Starter)

    vs.

    Separate Repos für Vorgaben zu Konzeptaufgaben und zum Dungeon-Starter

  • Variante D (Semester-Repo):

    Semester-Repo mit Orga, zeitlicher Zuordnung Woche/VL/Aufgaben/Abgaben/... und Links in die Webseite/ILIAS, Diskussionsforum

    vs.

    Lecture-Repo dient auch als Semester-Repo

Im Lecture-Repo würden dann nur noch echte Inhalte gesammelt, d.h. bei den Übungsblättern nur noch die Aufgaben-Fragmente. Die Inhalte des Lecture-Repo (Slides, Skript, evtl. Aufgaben) würden dabei als PDF und/oder als Webseite gerendert/bereitgestellt.

In einem Semester-Repo würde das dann konkret für das jeweilige Semester zugeordnet. d.h. dort hat man dann einen Table mit Woche, VL-Themen (Link auf die gerenderten Inhalte), Links auf Aufgaben(-fragmente) (Markdown), Abgabedaten, Abgabemodus, ... das ist eigentlich nix, was ins Lecture-Repo gehört (hier sollten nur inhaltliche Dinge rein). Das Semester-Repo (und ggf. das Aufgaben-Repo) werden als reine Markdown-Inhalte mit Preview in der GitHub-Oberfläche bereitgestellt. Das Semester-Repo wird nach jedem Semester archiviert und ggf. als Template für das Folgesemester benutzt (und danach gelöscht).

[cagix]

Am Ende gibt es praktisch zwei Varianten:

(a) Ein zentrales Lecture-Repo plus ggf. separate Hilfsrepos (Code-Vorgaben), Semester werden per Tag identifiziert
(b) Ein dauerhaftes Repo für das "Skript" plus ein Repo pro Semester plus separate Hilfsrepos für die Übungsaufgaben (semesterübergreifend? semesterweise?)

Variante (a) ist "self-contained", man hat über die Zeit nur ein zentrales Repo. Allerdings werden hier Inhalte und Organisation vermischt. Während sich die Vorlesungsinhalte eher langsam ändern, gibt es bei den Übungsaufgaben und den zugehörigen Vorgaben häufig stärkere Fluktuationen zwischen den Semestern.

Variante (b) wird beispielsweise von IUCompilerCourse gelebt: Lehrbuch, Kursseiten semesterweise (2021, 2022, 2023), Code-Vorgaben, ... Orga und Aufgaben finden sich in den Semester-Repos, Kommunikation könnte hier ebenfalls semesterweise stattfinden. Verweise auf das zentrale/dauerhafte Repo mit dem Skript/Buch.

---

Wenn wir die GitHub-Pages nutzen würden/könnten, wäre (b) verlockend - jedes Semester hätte sein eigenes kleines Repo mit Orga plus Discussions. Da der Content aber in ein Lernmodul im ILIAS deployed wird, macht das keinen Sinn mehr - es gibt eh nur eine Version (die aktuelle). Außerdem würde die Verlinkung in den Semester-Repos auf das Skript (-Repo) u.U. brechen, sobald im Skript-Repo Strukturen geändert werden. Und man muß die Orga-Seite immer wieder kopieren ...

In meinen anderen Modulen gibt es i.d.R. keine größeren Vorgaben für die Übungen und entsprechend keinen Bedarf für separate Hilfsrepos - (b) würde zu einem Organisations-Overkill führen.

---

Sommer 2024:

• Die Vorlesung bleibt im Lecture-Repo und wird von dort in das Lermodul überführt/deployed.
• Die Übungsaufgaben bleiben auch im Lecture-Repo, zeigen für die Vorgaben aber ggf. auf individuelle Repos.
• Discussions im Lecture-Repo werden für die Kommunikation (Ankündigungen, FAQ) genutzt und semesterweise neu erstellt/geschlossen.
• Die Semester-Orga ist das Readme.md im Lecture-Repo. Damit ändert sich diese jedes Jahr, aber es ist alles self-contained. Darauf achten, die Orga minimal zu halten (Erklärungen "extern" per Discussions).

Vorteil: Es bleibt bei einem Lecture-Repo plus ggf. einzelnen kleinen Vorgabe-Repos für die Aufgaben, damit bleibt auch die Verlinkung nach OERSI konstant. Einzelne Semester bekommen ein Tag und sind so später identifizierbar. (Bei der Alternative würde pro Semester ein neues Repo plus Verlinkung in OERSI hinzu kommen.)