diff --git a/documents/images/milestones/ms-6/qa-report/server_log.png b/documents/images/milestones/ms-6/qa-report/server_log.png new file mode 100644 index 0000000..acb3711 Binary files /dev/null and b/documents/images/milestones/ms-6/qa-report/server_log.png differ diff --git a/documents/images/milestones/ms-6/qa-report/vscode_code_coverage.png b/documents/images/milestones/ms-6/qa-report/vscode_code_coverage.png new file mode 100644 index 0000000..dd1ba82 Binary files /dev/null and b/documents/images/milestones/ms-6/qa-report/vscode_code_coverage.png differ diff --git a/documents/milestones/ms-6/qa-report.pdf b/documents/milestones/ms-6/qa-report.pdf new file mode 100644 index 0000000..05eb3cc Binary files /dev/null and b/documents/milestones/ms-6/qa-report.pdf differ diff --git a/documents/milestones/ms-6/qa-report.tex b/documents/milestones/ms-6/qa-report.tex new file mode 100644 index 0000000..4127160 --- /dev/null +++ b/documents/milestones/ms-6/qa-report.tex @@ -0,0 +1,250 @@ +\documentclass{article} +\setlength{\parindent}{0pt} +\usepackage[a4paper,margin=2.5cm]{geometry} +\usepackage{listings} + +% External links +\usepackage{hyperref} + +% Colored text +\usepackage{xcolor} +% Graphics +\usepackage{graphicx} + +% Customized table +\usepackage{float} +\usepackage{array} +\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}} +\usepackage{booktabs} + +% Create plots +\usepackage{pgfplots} +\usepackage{pgf-pie} + +\title{QS-Report für MS6} +\author{Syntax Syndicate - Casono} +\begin{document} +\maketitle + +\section{Einleitung} +Dieses Dokument ist die Fortsetzung des QA-Konzeptes für unser Mehrspieler-Spiel \textit{Casono}. +Es wurde von uns als Teil der Programmierprojekt-Vorlesung (ehemals bekannt als cs108) an der Universität Basel von uns entwickelt. + +Dieser Report folgt dem selben \textit{DIN ISO 9126}, und ist wie auch das Konzept für den ersten Teil in die selben Themenbereiche unterteilt: +\begin{itemize} + \item \textbf{Konstruktives Qualitätsmanagement} - Maßnahmen, die \emph{während} der Entwicklung ergriffen werden, um die Qualität von Anfang an sicherzustellen. + Einschließlich technischer Standards, Werkzeuge und internen Organisation. + \item \textbf{Analytisches Qualitätsmanagement} - Maßnahmen zur \emph{Kontrolle und Untersuchung} des bestehenden Produkts, durch Anwendung automatisierte Analysen, Metrik-Schwellenwerte und Unit-Tests. +\end{itemize} + +\section{Konstruktives Qualitätsmanagement} +Ein konstruktives Qualitätsmanagement umfasst alle Maßnahmen, die proaktiv Mängel verhindern, indem gemeinsame Standards, Prozesse und Werkzeuge festgelegt werden, die jedes Teammitglied während der Entwicklung einhält. + +\subsection{Technische Maßnahmen} + +\subsubsection{JavaDoc} +JavaDoc wurde genutzt um alle Öffentlichen Klassen, Interfaces, Records und Methoden zu dokumentieren. +Als Teil der GitLab-Build-Pipeline wird JavaDoc auf Richtigkeit überprüft. Werden strukturelle Fehler wie ungültige Referenzen erkannt, schlägt die Pipeline fehl und der Merge wird verhindert.\\ + +Unsere implizite Form für JavaDoc-Kommentare ist wie folgt: +\begin{itemize} + \item Eine prägnante Zusammenfassung in einem Satz in der ersten Zeile + \item Zusätzliche Informationen oder Beispiele in weiteren Absätzen. + \item Dokumentation aller Parameter (\texttt{@param}), Rückgabewerte (\texttt{@return}) und Fehler (\texttt{@throws}). +\end{itemize} +Leider konnten wir das in MS4 vorgenommene Ziel, das auch Warnungen zu einem Abbruch der Pipeline führen, aus Technischen Gründen nicht umsetzen. + +\newpage +\subsubsection{Logging} +Das Projekt verwendet Log4J~2 (\texttt{log4j-api} und \texttt{log4j-core} zur Laufzeit) zusammen mit Jansi für eine farbige Konsolenausgabe. +Das Format der Ausgabe ist durch eine Konfigurationsdatei vereinheitlicht.\\ + +Die Protokollstufen werden wie folgt einheitlich verwendet: +\begin{itemize} + \item \texttt{DEBUG} für interne Zustandsänderungen + \item \texttt{INFO} für Lebenszyklusereignisse wie Serverstart, Verbindungsaufbau/-trennung des Clients + \item \texttt{WARN} für behebbare Anomalien + \item \texttt{ERROR} für nicht behebbare Fehler +\end{itemize} + +Im Gegensatz zu MS4 wurden die Namen der Logger gekürzt und nicht mehr der gesamte Classpath verwendet. Ein Beispiel für die Ausgabe sieht so aus: +\begin{figure}[H] + \centering + \includegraphics[width=\textwidth]{../../images/milestones/ms-6/qa-report/server_log.png} + \caption{Konsolenausgabe des Servers während dem Verbindungsaufbau und Anmeldung eines Nutzers} +\end{figure} + +\subsection{Organisatorische Maßnahmen} + +\subsubsection{Teamkultur und die \texttt{CONTRIBUTORS}-Datei} +Das Stammverzeichnis des GitLab-Repositories enthält eine Datei namens \texttt{CONTRIBUTORS.md}, die die seit MS4 unveränderten Teamkonventionen dokumentiert: +\begin{itemize} + \item Die Verwendung von Branches - Feature-Branches werden in \texttt{main} zusammengeführt + \item Merge-Richtlinie - CI muss bestanden werden. Eine Genehmigung durch Kollegen ist wünschenswert wenn Änderungen an dessen Code vorgenommen wurden. + \item Namenskonventionen für Branches und Commits + \item Code-Stil - Google-Java-Format, AOSP-Variante, Einrückung mit vier Leerzeichen + \item Jede Änderung beginnt mit einem Issue oder Task in GitLab, bevor mit der Umsetzung begonnen wird + \item Branch-Namen folgen dem Muster \texttt{/} gemäß \href{https://conventional-branch.github.io/}{Conventional Branch} Standard + \item Commit-Messages folgen dem \href{https://www.conventionalcommits.org/en/v1.0.0/}{Conventional Commits} Standard + \item Code-Style wird durch Linter (Checkstyle) und Formatter (Spotless, Google/AOSP Java Style) automatisiert überprüft + \item Merge Anfragen müssen eine Beschreibung enthalten und auf das zugehörige Issue oder den Task verweisen + \item Zusammenarbeit und Kommunikation erfolgen bevorzugt über Issue-Kommentare, nicht über private Nachrichten +\end{itemize} + +\subsubsection{GitLab-Task- und Issue-Vorlagen für Fortschrittsverfolgung} +GitLab-Vorlagen für Tasks und Issues werden für alle geplanten Arbeitselemente verwendet. Die Aufgabenvorlage sorgt für eine einheitliche Struktur, die die Fortschrittsverfolgung erleichtert und das Risiko vager oder unvollständiger Arbeitselemente reduziert. + +Durch die Vergabe von Labels kann Tasks und Issues weiterer Kontext gegeben werden. + +\newpage +\section{Analytisches Qualitätsmanagement} + +\subsection{Analytische Verfahren} + +\subsubsection{Eigentumsrechte an Programmcode über GitLab \texttt{CODEOWNERS}} +In unserem Konzept haben wir uns vorgenommen, durch eine \texttt{CODEOWNERS} Datei den Teammitgliedern die Eigentumsrechte ihres Programmcodes zuzusprechen. Leider hat sich bestätigt das die von SciCORE betriebene Instanz nicht die Premium-Stufe hat, wodurch diese Funktion für uns nicht zur Verfügung steht. \\ + +Statt auf eine Automatisierte Grundlage zu vertrauen, haben wir uns für den nächstbesten Weg der Disziplinarität entschieden, wie am Beispiel von \href{https://git.scicore.unibas.ch/cs108-fs26/Gruppe-13/-/merge_requests/166}{dieser Merge-Anfrage} gesehen werden kann. + +\subsubsection{Automatisiertes CI-Linting und Build-Verifizierung} +Jeder Push und jede Merge-Anfrage löst die CI-Pipeline aus. + +Für Pushes und Merge-Anfragen setzt sich die Pipeline aus folgenden Phasen zusammen: +\begin{enumerate} + \item \textbf{Linting-Phase} \textcolor{blue}{[Push, MR]} - Checkstyle und Spotless überprüfen, ob der Programmcode dem vereinbarten Stil entspricht. + \item \textbf{Build-Phase} \textcolor{blue}{[Push, MR]} - \texttt{./gradlew assemble} prüft, ob das gesamte Projekt fehlerfrei kompiliert werden kann. + \item \textbf{Checkstyle-Report} \textcolor{blue}{[MR]} - Ein zusätzlicher Checkstyle-Report wird für Merge-Anfragen erzeugt und als Code-Quality-Report bereitgestellt. + \item \textbf{Javadoc-Prüfung} \textcolor{blue}{[MR]} - JavaDoc wird auf Korrektheit geprüft. + \item \textbf{Test-Phase} \textcolor{blue}{[Push, MR]} - Automatisierte Tests werden ausgeführt und ein Testreport erzeugt. +\end{enumerate} +Die Entscheidung das fehlgeschlagene Jobs keinen Push aber dafür eine Merge-Anfrage verhindern können, hat sich als vernünftig bewehrt. +Über die Dauer des Projektes hat diese Pipeline mehrmals verhindert das Fehlerhafter oder sogar kaputter Programmcode in den main Branch gelangen konnte. + +\newpage +\subsection{Testverfahren} +Unit-Tests wurden mit \textit{JUnit 5} geschrieben und in der Testphase der CI-Pipeline ausgeführt. Ein fehlgeschlagener Test blockiert die Merge-Anfrage. + +Als weiteres Werkzeug verwendeten wir \textit{JaCoCo} für die Ermittlung der Testabdeckung. \\ +Die Testabdeckung für Meilenstein sechs ist wie folgt: + +\begin{table}[H] + \centering + \renewcommand{\arraystretch}{1.4} + \begin{tabular}{L{7.5cm} r r} + \textbf{Paketname (gekürzt)} & \textbf{Instr.\ Cov.} & \textbf{Branch Cov.} \\ + \midrule + \texttt{client.chat} & 30\,\% & 16\,\% \\ + \texttt{client.game} & 15\,\% & 2\,\% \\ + \texttt{client.network} & 2\,\% & 1\,\% \\ + \texttt{client.ui} (von Abdeckung ausgeschlossen) & 0\,\% & 0\,\% \\ + \texttt{server.app.checks} & 0\,\% & 0\,\% \\ + \texttt{server.app.commands} & 0\,\% & 0\,\% \\ + \texttt{server.domain.game} & 68\,\% & 43\,\% \\ + \texttt{server.domain.*} & 59\,\% & 44\,\% \\ + \texttt{server.network.transport} & 0\,\% & 0\,\% \\ + \texttt{server.network.protocol} & 67\,\% & 55\,\% \\ + \texttt{server.network.*} & 67\,\% & 55\,\% \\ + \midrule + \textbf{Summe} & \textbf{18\,\%} & \textbf{11\,\%} \\ + \bottomrule + \end{tabular} +\end{table} + +Im vierten Meilenstein haben wir uns das Ziel gesetzt die Testabdeckung für die Game-Engine und wichtige Netzwerkkomponenten auf mindestens 50\% zu erhöhen, dieses Ziel haben wir laut JaCoCo nicht erreicht.\\ +Geht man jedoch nach der Abdeckung der "Test Runner for Java" Erweiterung in VSCode, dann beträgt die Abdeckung 51\%. Sowohl Julian (Game-Engine) als auch Lars (Serverseitiges Netzwerk) haben sich nach diesen Angaben gereichtet, weshalb wir dachten wir hätten unser Ziel erreicht. + +\begin{figure}[H] + \centering + \includegraphics[width=0.4\textwidth]{../../images/milestones/ms-6/qa-report/vscode_code_coverage.png} + \caption{Abweichende Angaben bezüglich der Abdeckung von VSCode zu JaCoCo} +\end{figure} + +Die Verwendung zwei unterschiedlicher Tools zur Beurteilung des Fortschritts ist definitiv etwas, was es in Zukunft zu vermeiden gilt. + +\newpage +\section{Metriken} +\textit{Die nachfolgenden Metriken wurden am 17. Mai 2026 um 20:58 Uhr erhoben, neuere Änderungen sind daher nicht berücksichtigt.} + +\subsection{Lines of Code} +\begin{figure}[H] + \centering + \begin{tikzpicture} + \begin{axis}[ + width=\textwidth, + height=0.45\textwidth, + xlabel={Meilenstein}, + ylabel={Zeilen}, + ymin=0, + ymax=31000, + xtick={1,2,3}, + xticklabels={MS4,MS5,MS6}, + legend pos=north west, + grid=both, + scaled y ticks=false, + yticklabel style={/pgf/number format/fixed} + ] + + % Actual Java code + \addplot[ + color=blue, + mark=o, + thick + ] + coordinates { + (1,9760) + (2,12972) + (3,15319) + }; + \addlegendentry{Java code (actual)} + + % Total Java + \addplot[ + color=red, + mark=square*, + thick + ] + coordinates { + (1,16396) + (2,21203) + (3,24319) + }; + \addlegendentry{Java total} + + % Total in src + \addplot[ + color=green!60!black, + mark=diamond*, + thick + ] + coordinates { + (1,18012) + (2,22872) + (3,29639) + }; + \addlegendentry{Total in src} + + \end{axis} + \end{tikzpicture} + \caption{Entwicklung der Java-Zeilen (tatsächlicher Code vs. Gesamt) über die Meilensteine hinweg} +\end{figure} + +\subsection{Verteilung der Code-Zeilen auf verschiedene Dateitypen} +\begin{figure}[H] + \centering + \begin{tikzpicture} + \pie[ + text=legend, + radius=4 + ]{ + 62.26/Java, + 17.19/PostCSS, + 14.90/Markdown, + 2.87/XML, + 2.79/HTML + } + \end{tikzpicture} + \caption{Verteilung der Code-Zeilen (Top 5 Dateitypen)} + \label{fig:loc-pie} +\end{figure} + +\end{document}