‏ ‏ ‎

1. Allgemeines

  • Bezeichner sind in Kleinbuchstaben zu schreiben (lower case).

    • Dafür gibt es viele Gründe, zB

      lowercase

    • Besonders bei Großbuchstaben in einem Repository-Namen können Probleme auftreten - auch beim Deployment in die LeoCloud

    • jedoch: Ausnahmen bestätigen die Regel

2. Dokumentation

2.1. Form der Dokumentation

  • Die Dokumentation ist in einem Markup-Dialekt zu erstellen (zB asciidoctor, markdown)

  • Die Grafiken sind vorzugsweise mittels plantuml oder einem ähnlichen textbasierten Tool/Framework zur Diagrammerstellung anzufertigen.

  • Als Vorlage wird das Repo asciidoctor-html-template empfohlen.

    Hier werden automatisch aus den adoc-Files mittels gh-actions statische Webseiten (gh-pages) erstellt.

2.2. Inhalte der Dokumentation

Wie bereits im Abschnitt _README erwähnt, besteht eine Dokumentation aus folgenden Teilen:

2.2.1. Dokumentation des bestehenden Systems (Legacy System, Istzustand)

  • Datenmodell

  • Schnittstellen

2.2.2. Dokumentation des zu erstellenden Systems (Sollzustand)

  • Datenmodell

  • Schnittstellen zwischen Komponenten

  • Schnittstellen nach außen

  • ev. Wireframes und/oder Screenshots

  • Benutzerhandbuch (falls notwendig)

  • Installationshandbuch

    • Installation/Deployment des Systems

    • Starten des Systems

    • Backup des Systems

2.2.3. Besprechungsprotokolle (Minutes-of-Meeting)

Ergebnisprotokolle keine Gesprächsverlaufsprotokolle

  • Sämtliche Gespräche mit Lehrpersonen und/oder (externen)Auftraggebern sind mittels Ergebnisprotokoll zu dokumentieren.

  • Die Struktur des Protokolls soll einheitlich sein. Eine mögliche Vorlage ist minutes-of-meeting.adoc

  • Die Benennung der Dokumente soll einem Schema entsprechen:

    yyy-mm-dd_<Art des Dokuments>_<Thema des Dokuments>.adoc

    zB 2025-02-24_Besprechung_Thema_XY.adoc

  • siehe auch Franklyn 3

2.2.4. Statusberichte

2.2.5. Foliensätze (RevealJS-slides)

Bsp: Projekt Franklyn 3

2.2.6. Sonstiges

3. git-Repositories

3.1. Struktur der Repos

Wir verwenden grundsätzlich Monorepos.
projekt repo struktur
folder content Bsp

frontend

spa + docker-files

C.Aberger - Keycloak

compose

Konfiguration für docker-compose, Dockerfiles für zB keycloak, postgres, …​

C.Aberger - Keycloak

k8s

Konfiguration für kubernetes

C.Aberger - Keycloak

3.2. README

  • README.adoc oder README.md

  • Kurze Beschreibung der Projektaufgabe

    • ev. User Stories oder Use-Case-Diagram

    • ev. Klassendiagramm und/oder ERD

  • Wie kann man das Projekt in Betrieb nehmen?

    • Welche Voraussetzungen sind notwendig

    • Wie startet man die Software-Produkte (zB Docker-Container)

    • Wo findet man die Artefakte (meist im gh-Repo)

    • Link zum scrum-board (zB youtrack)

    • ev. Link zu den Folien

  • Projektteam

    • Minimum: Vor- und Nachnamen, Klasse und Jahrgang

  • Beispiele:

3.3. Inhalt eines git-Repos

3.3.1. Was gehört in ein git-Repo?

  • Sämtliche Artefakte, die man selbst erstellt: zB

    • Programmcodes

    • Dokumentationen

    • Scripts

    • Struktur eines .env-Files mit Dummy-Konfigurationsdaten

3.3.2. Was gehört NICHT in ein git-Repo?

  • Sämtliche Artefakte, die generiert werden: zB

  • node_modules und target-Verzeichnis

  • Die IDE-Verzeichnisse wie .idea und .vscode

  • Keine Passwörter und persönliche Daten. Verwenden Sie hierzu git-secrets und dgl.

  • .env-Files mit vertraulichen Konfigurationsdaten

3.4. Commit-Messages

Types of Commit-Messages

  • feat – a new feature is introduced with the changes

  • fix – a bug fix has occurred

  • chore – changes that do not relate to a fix or feature and don’t modify src or test files (for example updating dependencies). Often bump is used for updating a version.

  • refactor – refactored code that neither fixes a bug nor adds a feature

  • docs – updates to documentation such as a the README or other markdown files

  • style – changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.

  • test – including new or correcting previous tests

  • perf – performance improvements

  • ci – continuous integration related

  • build – changes that affect the build system or external dependencies

  • revert – reverts a previous commit

3.5. gh-Pages

  • Der Link zu den gh-Pages ist immer unter About einzutragen

link to gh pages
Konfiguration der gh-pages
configuration gh pages

4. git Branching Strategy

4.1. 3. Jahrgang

git branching strategy jg3
Figure 1. source: Brenton Cleeland: Git branching strategy diagrams

  • Entwickeln der Features in Feature-Branches.

  • Der main-Branch ist immer lauffähig.

  • Die Releases sind zu taggen.

4.2. 4. Jahrgang

git branching strategy jg4
Figure 2. source: Design Patterns for Salesforce Git Branching Strategies

  • Der main-Branch enthät nur mehr die Releases.

  • Jeder Release wird getagged.

  • Der develop-Branch ist immer lauffähig.

  • In diesem Projekt sieht man die Verwendung des develop-Branches

5. Planung und Dokumentation der Programmierarbeiten

Im Rahmen des Projektunterrichts wird versucht nicht einfach drauf los zu coden, sondern zuerst Tasks in einem Scrum Board zu erstellen und diese dann abzuarbeiten. Für jeden Task soll dann ersichtlich sein, welche Commits zu dessen Erfüllung geführt haben

5.1. User Stories und Tasks

  • Das Scrum-Board sowie das Repo sind zu "verbinden", dh sämtliche Commits eines Tasks werden im Scrum-Board angezeigt.

  • Für sämtliche Arbeiten sind Tasks (und die dazugehörigen User Stories) zu erstellen

    • Für jeden Commit ist in der Commit-Message die dazugehörige Task-Id einzutragen.

Tasks und Commit-Messages
youtrack task
youtrack task commit

5.2. Releases

  • Wird eine Version deployed, ist ein entsprechender Release zu dokumentieren:

github repo
github release

  • Die Änderungen werden automatisch eingetragen, daher sind aussagekräftige Commit-Messages essenziell.

github package

6. Deployment

7. Weitere Aspekte im Projektablauf

7.1. Security

  • In einem ersten Schritt wird auf die Security verzichtet, die Funktionalität steht im Vordergrund.

  • Beispiel: Nicht bereits am Anfang Zeit mit Login-Screens verschwenden.

Beim ersten Deployment auf einem Server oder in der Leocloud sind allerdings Schutzmaßnahmen zu ergreifen.

7.2. Backups

  • Für Auftragsarbeiten ist auch zu überlegen und vorzuschlagen, wie für die Datenbank(en) Backups erstellt werden können.

7.3. Versionierung der Datenbanken

  • Bei Anwendung von Scrum entwickelt sich die Applikation in Etappen (Sprints). Dadurch kann sich auch die Datenbankstruktur (oft) ändern.

  • Es wird daher empfohlen, ein Datenbankversionierungstool wie Flyway oder Liquibase zu verwenden.

8. Für Lehrkräfte: git-Classroom

8.1. Erstellen der Repos

  • Projekte sollten von der jeweiligen Lehrkraft mittels gh-classroom erstellt werden.

    projekte gh classroom

    • Nachdem die Lehrkraft die Rahmenbedingungen festgelegt hat, erstellen die Schüler ihre Projekte.

    • Dies hat den Vorteil, dass die Projekt-Repos der Lehrkraft zugeordnet sind und die Schüler uneingeschränkt Zugriff auf die Repositories haben.

8.2. Virtuelle Maschinen

  • Möglichkeiten

    • oravm

    • vm vom sysadmin

    • leocloud (mandatorisch, spätestens ab 4.jg, 2.Semester)

Vor der Matura die Credentials einsammeln und aufbewahren.