first version of documentation overhaul

README.md

+# Wissenstest (Praktikum zur Lehrveranstaltung Datenbanken 2)
 
+Diese Repository bildet die Grundlage für Ihr Praktikum in Datenbanken 2. Sie werden auf seiner Basis über das gesamte Semester verteilt in mehreren Schritten ein Wissensquiz entwickeln. 
+Zu diesem Zweck werden wir Git und GitLab einsetzten. Sollten Sie mehr informationen und Hilfe zu den beiden Tools benötigen, gucken Sie bitte [hier](readme/gitandgitlab.md).
 
-## Checkstyle Plugin
+in diesem Dokument finden Sie die folgenden Informationen: 
+- [Fachliche Projektbeschreibung](#fachliche-projectbeschreibung)
+- [Technische Projektbeschreibung](#technische-projektbeschreibung)
+- [Hinweis zur Autorenschaft](#hinweis-zur-autorenschaft)
 
-[Descriptions of styles](http://checkstyle.sourceforge.net/style_configs.html)
+Hier finden Sie nun eine fachliche Projektbeschreibung des zu Implementierden Spiels
 
-Google: https://github.com/google/google-api-java-client/blob/dev/checkstyle.xml
+# Fachliche Projektbeschreibung
+
+## Projektidee
+Ziel des Projekts ist die Entwicklung des Spiels „Wissenstest“, mit dem man sein Wissen in verschiedenen Wissensgebieten (Kategorien) testen kann.
+
+## Datenbasis
+Auf dem Datenbankserver werden zu unterschiedlichen Kategorien Fragen gespeichert.
+Zu jeder Frage gibt es genau vier Antworten, von denen genau eine richtig ist und folglich drei falsch sind.
+
+Jede Frage gehört zu genau einer Kategorie.
+
+Eine Basis von Kategorien, Fragen und Antworten als Stammdaten wird in einer entsprechenden `csv`-Datei zur Verfügung gestellt. Die `csv`-Datei finden Sie im Unterordner `/src/main/resources/`. Sie trägt den Namen: `Wissenstest_sample200.csv`.
+
+## Spielbeschreibung
+Wenn ein Spieler ein Spiel spielt, wählt er zunächst eine beliebige Anzahl von Kategorien aus (mindestens zwei) und lässt sich hierzu zufällig eine maximale Anzahl von Fragen generieren. Diese maximale Anzahl der Fragen pro Kategorie wird pro Spiel zu Beginn ebenfalls festgelegt und ist dann für alle Kategorien innerhalb eines Spiels gleich.
+Aus den angebotenen vier Antworten muss der Spieler genau eine auswählen – er bekommt sofort eine Auskunft darüber, ob die ausgewählte Antwort richtig oder falsch war.
+Sehen Sie für jedes Spiel die folgenden Informationen vor:
+- Spieler
+- Timestamp Start, Timestamp Ende
+- Liste der Kategorien, Liste der Fragen und ausgewählte Antwort
+
+Von jedem Spieler sollte (mindestens) der eindeutige Spielername gespeichert sein.
+
+**Hinweis**: Wollen Sie weitere Attribute vorsehen, sprechen Sie dies mit Ihrem Praktikumsbetreuer ab, da diese in Konflikt mit Abfragen aus Praktikum 5 stehen könnten.
+
+## Auswertung
+Haben mehrere Spieler das Spiel gespielt, so gibt es die Möglichkeit, Analysen unterschiedlichster Art zu einem oder mehreren Spielern aufzurufen. Welche Analysemöglichkeiten implementiert werden, ist Bestandteil des Praktikums 5.
+
+
+# Technische Projektbeschreibung
+
+## Projektrahmen
+Im diesem Repository finden Sie einen Projektrahmen, den Sie für die Impelemntierung des gesamten Projektes verwenden sollen. Unter anderem bringt er eine Package-Struktur mit, in die Sie Ihren Code einfügen sollen. Konkret heißt dies, dass alle von Ihnen erzeugten Klassen in `de.hda.fbi.db2.stud` oder von ihnen erstellte Unterordner in dem Package zu erstellen sind. 
+
+Darüber hinaus, bringt der Projektrahmen noch die folgenden Dinge mit: 
+- Gradle Projekt: fertiges Projekt, damit Sie direkt mit der Entwicklung anfangen können. Weitere Informationen zu Gradle finden Sie [hier](https://gradle.org/)
+- Vorberietete JPA Resourcen (z.B. `persistance.xml`)
+- Datenbasis als `csv`-Datei. Die Datei finden Sie im Unterordner `/src/main/resources/Wissenstest_sample200.csv`
+- Parser für die Datenbasis. Sie finden diesen im Package: `de.hda.fbi.db2.tools.CsvDataReader`
+- CI/CD Pipeline (details siehe unten) zum Bauen und Testen Ihres Projektes auf dem GitLab Server
+
+Weiter Hinweise wie sie das Projekt bei sich Lokal clonen und in IntelliJ verwenden finden sie [hier](readme/gitandgitlab.md)
+
+## Benötigte Software für die Arbeit mit Git bzw. GitLab
+Sie benötigen für dieses Praktikum die [IDE IntelliJ](https://www.jetbrains.com/idea/) IDE mit [Gradle-Plugin](https://docs.gradle.org/current/userguide/idea_plugin.html) (automatisch Teil von IntelliJ) und JDK8
+- Für IntelliJ ist **vorab** eine kostenlose Registrierung als Student notwendig.
+- Andere IDEs sind möglich, werden im Praktikum aber nicht unterstützt.
+
+Wir empfehlen, zusätzlich zum in IntelliJ integrierten Git-Client die Software TortoiseGIT zu installieren:
+- Unter Windows: [TortoiseGIT](https://tortoisegit.org/) integriert sich in den Windows-Explorer, sodass alle Funktionen im Explorer über das Kontextmenü (rechte Maustaste) aufrufbar sind. Zur Nutzung von TortoiseGIT benötigen Sie außerdem GitForWindows.
+- Falls Sie Linux verwenden, installieren Sie ein git package Ihrer Wahl. Aber, ganz ehrlich, wenn Sie Linux verwenden, wissen Sie genau was zu tun ist. 
+
+## Continuous Integration Pipeline
+Der GitLab Server führt automatisch Builds und Tests Ihrer Commits durch. Damit können Sie und wir schon im Vorfeld prüfen, ob Ihr aktueller Stand den Anforderungen entspricht. 
+Wie oben beschrieben, setzen wir dabei voraus, dass Sie Ihr Projekt in dem von uns vorgesehenem Package entwickeln: `de.hda.fbi.db2.stud`. Wenn Sie sich nicht an diese Anforderung halten, erhalten Sie kein Testat! Den Stand Ihrer Builds und Tests können Sie links in Ihrem Repository über das Menu "CI/CD" → "Pipelines" abrufen.
+
+Die Pipeline verwendet die folgenden zwei Tools: 
+- [Checkstyle](http://checkstyle.sourceforge.net/) ist ein Werkzeug zur statischen Code-Analyse zur Prüfung des Programmierstils von Java-Sourcecode. Konkret verwenden wir im Praktikum Google's Java Code Style. Eine Beschreibung können Sie [hier](http://checkstyle.sourceforge.net/google_style.html) finden. 
+- [Spotbugs](https://spotbugs.github.io/) such in Java-Programmen nach Fehlermustern. Solche Fehlermuster deuten oft auf tatsächliche Fehler hin.
+
+
+## Nutzen der Checkstyle und Spotbugs in IntelliJ
+Bevor Sie ihren Code zum GitLab Server pushen, sollten Sie local mit Hilfe von Spotbugs und Checkstyle überprüfen lassen ob die Pipeline Fehler finden wird. Dafür rufen Sie einfach in IntelliJ den Gralde task `build` auf. In der Consolenausgabe werden entsprechende Fehler angezeigt. 
+
+Erzeugte Reports finden Sie local im Projekt unter `/build/reports/`.
+
+
+## Konfiguration von IntelliJ zur Verewndung des Google Style Checker
+IntelliJ verwendet standardmäßig im Editor für Style Checking **nicht** Google's Java Code Style. Dies sollten Sie manuell konfigurieren. Sie tun dies indem Sie die Einstellungen von IntelliJ öffnen (File → Settings → Editor → Code Style) und wählen bei Import Schema (siehe Screenshot) 
+Sie finden die nötige Datei im Projektornder unter: `/readme/intellij-java-google-style.xml`
+
+![IntelliJ Änderung Coding Style](readme/intellij-googlestyleplugin.png)
+
+
+# Hinweis zur Autorenschaft
+Dieses Projekt wurde durch die Mitglieder der [Fachgruppe Datenbanken](https://fbi.h-da.de/fachbereich/fachgruppen/datenbanken/) gemeinsam entwickelt und seitdem gepflegt. 
 

readme/gitandgitlab.md

+# Einführung in Git und GitLab
+
+## Ziel
+[Git](https://git-scm.com/) ist eine populäre Software zur (verteilten) Versionsverwaltung von Dateien. Sie wurde initial von [Linux Torvalds](https://en.wikipedia.org/wiki/Linus_Torvalds) für den [Linux Kernel](https://en.wikipedia.org/wiki/Linux_kernel) enwickelt und gilt heute als Standard in der Software Entwicklung. 
+
+[GitLab](https://about.gitlab.com/) ist, ähnlich wie [GitHub](https://github.com/), eine Weboberfläche zum Verwalten von Git-Repositories. Das folgende Dokument führt in die für dieses Praktikum benötigte Infrastruktur und Software ein.
+
+## Clonen eines Projekts von Gitlab
+Um die Arbeit zu erleichtern, finden Sie in diesem Repository einen vorbereiteten Projektrahmen. Als erstes müssen Sie sich eine lokale Kopie des Projektes erzeugen – dieser Schritt heißt bei Git clonen. Sie können das Clonen mit den installierten Git-Tools (vgl. „Benötigte Software für die Arbeit mit Git“) über das Dateisystem (git clone) oder über **IntelliJ** ausführen:
+
+- VCS → Git → Clone
+- Im Feld  URL die URL Ihres Repositorys eintragen.
+- Unter Directory ein geeignetes Verzeichnis auf Ihrem Rechner auswählen.
+- Alle weiteren Angaben im IntelliJ-Dialog können Sie unverändert übernehmen.
+
+Das vorbereitete Projekt kann in IntelliJ direkt und ohne weitere Anpassungen verwendet werden. Das eingesetzte Build-Automatisierungssystem heißt Gradle und muss von Ihnen in der Regel nicht angepasst werden, da bereits alles lauffähig konfiguriert ist und stelle eine Menge vorbereiteter Tasks, wie check, build, run, etc., zur Verfügung.
+Der Projektrahmen ist in folgende Bereiche aufgeteilt:
+- In src → main → java werden die Java-Sources abgespeichert. Das Package de.hda.fbi.db2 ist bereits eingerichtet.
+- In src → main → resources werden die zum Projekt gehörenden Ressource-Dateien abgespeichert.
+
+**Hinweis**: Alle von Ihnen entwickelten Java-Klassen und -Packages müssen als Unter-Packages von de.hda.fbi.db2.stud abgelegt werden, damit der automatisierte Build-Prozess (vgl. „Weitere Hinweise zur Arbeit mit GitLab“) funktioniert!
+
+**Beispiel**:	de.hda.fbi.db2.stud.entity
+
+### Wichtige Git-Kommandos
+**Add** *(Selektieren Ihrer Änderungen zum Commit)*:    `git add`<br/>
+Add registriert Dateien im Git für den nächsten Commit. Dabei ist zu beachten, dass bei Anwendungen nur der Quellcode, nicht aber die fertigen Libraries/Programme hinzugefügt werden dürfen!
+
+*Bitte adden und committen Sie Ihre Projekt-Dateien ausschließlich über IntelliJ!* Die Funktion Add ist nur für zusätzliche Dateien außerhalb des Projektordners gedacht.
+
+
+**Commit** *(Hinzufügen Ihrer Änderungen zum lokalen Repository)*:    `git commit`<br/>
+Dieses Kommando fügt Ihre Änderungen zum lokalen Repository hinzu. Sie müssen hierbei eine Commit-Message angeben, welche die Änderungen beschreibt. Eine Übertragung zum Server findet, im Gegensatz zu SVN, beim Commit nicht statt!
+
+
+**Push** *(Übertragen Ihrer Änderungen auf den Server)*:  `git push`<br/>
+Überträgt Ihre Änderungen zum Git-Server. Ggf. muss vorher ein Pull gemacht werden.
+
+
+**Pull** *(Abrufen von Änderungen vom Server)*:   `git pull`<br/>
+Lädt Änderungen vom Server herunter. Ggf. müssen diese Änderungen mit den lokalen Änderungen zusammengefügt (merge) werden.
+
+Für Studierende, die über keine Erfahrung mit Git verfügen, empfehlen wir, nicht gleichzeitig an mehreren Rechnern zu arbeiten, und jeweils unmittelbar *vor* der Arbeit ein Pull und unmittelbar *nach* der Arbeit ein Push zu machen (Commit vor dem Push nicht vergessen!). 
+
+Des weitern empfehlen wir unerfahrenen Studierenden folgende Links:
+- [Buch: *Git Pro*](https://git-scm.com/book/en/v2) (verfügbar in verschiedenen Sprachen)Gutes Buch zu Git, mit vielen (sehr vielen) Beispielen. Das Buch steht unter Creative Commons Attribution Non Commercial Share Alike 3.0 license. Es ist in verschiedenen Sprachen und Formaten verfügbar.
+- [Comparing Workflows](https://www.atlassian.com/git/tutorials/comparing-workflows)  eine gute Einführung in die Git-Workflows.
+- [learngitbranching.js.org](https://learngitbranching.js.org/) Tutorial zum Thema Git Branching
+