Aufgabe 03 - Repository, Dokumentationsgerüst und Entscheidungsprotokoll

Aufgabe 03 - Repository, Dokumentationsgerüst und erstes Entscheidungsprotokoll

Worum geht es?

Sie legen das Repository an, in dem dieses Projekt das ganze Jahr wächst, richten die Dokumentationsstruktur ein und schreiben den ersten Eintrag ins Entscheidungsprotokoll: den Schnitt zwischen Frontend, Webservice und Inhaltsbereich (siehe Kapitel Jahresprojekt: Thema und Team). Der Umgang mit Geheimnissen wird dabei von Anfang an richtig eingerichtet, weil er sich später nicht nachholen lässt.

Was Sie dafür brauchen

• Kapitel Jahresprojekt: Thema und Team, Abschnitte Den Schnitt festlegen und Repository und Dokumentation.
• Die Ergebnisse aus den Aufgaben 01 und 02.
• Git und ein Konto auf der Plattform Ihrer Klasse.

Welche Kompetenzen Sie erwerben und zeigen

• Sie setzen ein Repository mit Dokumentations- und Entscheidungsstruktur auf.
• Sie begründen den Schnitt Ihres Projekts und benennen die Alternative, die Sie verworfen haben.
• Sie richten den Umgang mit Geheimnissen so ein, dass kein Zugangsdatum in die Historie gerät.

Pädagogische Einordnung

• Reproduktion: die vorgegebene Struktur anlegen und die Regeln der Zusammenarbeit aufschreiben (Teil A).
• Reorganisation und Transfer: die eigene Architektur darstellen und in einer Skizze festhalten (Teil B).
• Reflexion, Problemlösung und Urteilsbildung: eine Architekturentscheidung begründen und ihre Folgen einschätzen (Teil C).

Ein committetes Passwort ist verbrannt

Ab dieser Übung gilt die Regel zum ersten Mal: Ein Zugangsdatum, das einmal committet wurde, steht in der Historie und liegt bei jedem, der das Repository geklont hat. Der einzige wirksame Schritt ist dann, das Geheimnis zu wechseln.

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt.

Teil A - Das Gerüst

1. Legen Sie das Repository an und darin diese Struktur:

   projekt/
   ├── README.md
   ├── .env.example
   ├── .gitignore
   ├── docs/
   │   ├── architektur.md
   │   ├── betrieb.md
   │   ├── entscheidungen.md
   │   └── haertung.md
   └── src/

2. Schreiben Sie die README.md. Sie beantwortet genau eine Frage: Wie bringt eine fremde Person dieses Projekt auf ihrem Rechner zum Laufen? Halten Sie sich an eine Bildschirmseite. Hineingehören mindestens: was das Projekt tut (zwei Sätze), welche Software vorher installiert sein muss, die Befehle zum Starten in der richtigen Reihenfolge, und die Adresse, unter der die Anwendung danach erreichbar ist.

3. Tragen Sie in .gitignore mindestens .env, .env.*, node_modules und Ihre Bauverzeichnisse ein.

4. Legen Sie .env.example an. Hinein kommt jeder Variablenname, den Ihr Projekt bereits absehbar braucht, dazu je ein Kommentar mit der Bedeutung. Echte Werte kommen keine hinein, auch keine Beispielpasswörter, die echt aussehen.

5. Schreiben Sie die Regeln der Zusammenarbeit in die README.md oder eine eigene CONTRIBUTING.md. Vier Punkte genügen: was für main gilt, wie eine Zusammenführung abläuft, wie Commit-Betreffzeilen aussehen, und wer das Repository verwaltet. Im Team kommen drei Absprachen dazu: wer welchen Bereich in welchem Zeitraum übernimmt, wer den Server bezahlt und auf wessen Namen er läuft, und wer Zugriff hat.

6. Legen Sie die Projektskizze aus Aufgabe 01 als docs/projektskizze.md ab.

7. Setzen Sie drei Commits ab und rufen Sie git log --oneline auf. Prüfen Sie, ob Ihre Betreffzeilen der Regel aus Punkt 5 entsprechen, und schreiben Sie das Ergebnis der Prüfung auf.

Teil B - Die Architekturskizze

1. Zeichnen Sie die Systemlandschaft Ihres Projekts nach dem Vorbild im Kapitel. Verwenden Sie Ihre eigenen Namen für die Kästen. Bei einem Fullstack-Projekt fallen Frontend und Webservice zu einem Kasten zusammen, alles andere bleibt.

2. Legen Sie die Skizze zusammen mit der Domänenskizze aus Aufgabe 02 in docs/architektur.md ab.

3. Notieren Sie darunter die drei Angaben, die jetzt schon feststehen müssen: Wunschname der Domain, Anzahl der Sprachen in der Oberfläche, und die Größenordnung der Daten. Für die dritte Angabe rechnen Sie überschlägig vor, wie viele Datensätze nach einem Jahr Betrieb zusammenkommen, etwa: 40 Mitglieder, im Schnitt zwei Buchungen pro Woche, ergibt rund 4000 Buchungen im Jahr.

4. Notieren Sie darunter die Punkte, die ausdrücklich offen bleiben, und zu jedem das Kapitel, das ihn beantwortet. Mindestens diese drei gehören dazu: die konkreten Bibliotheken, die Auswahl des CMS (Kapitel 14) und die Rendering-Strategie (Kapitel 13).

Teil C - Die erste Entscheidung

1. Entscheiden Sie den Schnitt Ihres Projekts: Next.js-Fullstack oder getrennte Anwendungen. Gehen Sie dafür die sechs Zeilen der Vergleichstabelle im Kapitel durch und notieren Sie zu jeder Zeile, welche Variante für Ihr Projekt besser abschneidet und warum.

2. Schreiben Sie den Eintrag in docs/entscheidungen.md mit Datum, Status und den vier Abschnitten aus dem Kapitel: Entscheidung, Alternativen, Begründung, Folgen.

3. Im Abschnitt Alternativen steht die verworfene Variante mit ihrem stärksten Vorzug, nicht mit ihrer größten Schwäche. Wer nur Nachteile aufzählt, hat nicht verglichen, sondern sich nachträglich recht gegeben.

4. Im Abschnitt Folgen stehen mindestens drei Punkte, jeder mit einem Kapitelbezug. Prüfen Sie dafür, was Ihre Entscheidung in den Kapiteln 3, 4, 5 und 8 nach sich zieht.

5. Legen Sie einen zweiten Eintrag nach demselben Muster an, für eine weitere Entscheidung, die Sie bereits getroffen haben. In Frage kommen die Plattform des Repositories, die Teamgröße, der Domainname oder das Betriebssystem des Servers.

6. Beschreiben Sie in vier bis fünf Sätzen, was sich an Ihrer Architekturskizze, am Deployment und an der Anmeldung ändern würde, wenn Sie sich beim Schnitt anders entschieden hätten. Nennen Sie zum Schluss den Zeitpunkt, ab dem ein Wechsel nicht mehr in Frage kommt, und begründen Sie ihn mit dem, was bis dahin gebaut ist.

7. Legen Sie in docs/betrieb.md eine leere Tabelle mit den Spalten Datum, Eingriff, Grund, Ergebnis an. Legen Sie in docs/haertung.md die Überschriftenstruktur an. Ab dem nächsten Kapitel wird beides gefüllt.

Wissenscheck

1. Welche Frage beantwortet die README.md, und was sagt es über das Projekt aus, wenn die Antwort zwei Seiten braucht?
2. Warum steht in .env.example jeder Variablenname, aber kein einziger Wert?
3. Warum genügt es nicht, ein versehentlich committetes Passwort im nächsten Commit zu löschen?
4. Welche vier Abschnitte hat ein Eintrag im Entscheidungsprotokoll, und wozu dient der Abschnitt Folgen?
5. Warum gehört die verworfene Alternative mit ihrem stärksten Vorzug ins Protokoll?
6. Was spricht bei einer Einzelperson für den Fullstack-Schnitt, was bei einem Dreierteam für getrennte Anwendungen?
7. Warum wird die Betriebsdokumentation im September begonnen und nicht im Juni geschrieben?

Abgabe

Das angelegte Repository mit README.md, .gitignore, .env.example und dem vollständigen docs/-Gerüst. In docs/architektur.md liegen Systemlandschaft und Domänenskizze samt den festen und offenen Punkten. In docs/entscheidungen.md stehen zwei Einträge, einer davon zum Schnitt. Die Zeilenbewertung aus Teil C Punkt 1 und die Antwort aus Punkt 6 stehen in protokoll.md.