diff --git a/documents/milestones/ms-4/qa-concept.pdf b/documents/milestones/ms-4/qa-concept.pdf new file mode 100644 index 0000000..da93649 Binary files /dev/null and b/documents/milestones/ms-4/qa-concept.pdf differ diff --git a/documents/milestones/ms-4/qa-concept.tex b/documents/milestones/ms-4/qa-concept.tex new file mode 100644 index 0000000..85474b3 --- /dev/null +++ b/documents/milestones/ms-4/qa-concept.tex @@ -0,0 +1,144 @@ +\documentclass{article} +\setlength{\parindent}{0pt} +\usepackage[a4paper,margin=2.5cm]{geometry} +\usepackage{listings} + +% External links +\usepackage{hyperref} + +% Colored text +\usepackage{xcolor} + +% Customized table +\usepackage{float} +\usepackage{array} +\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}} +\usepackage{booktabs} + +\title{QS-Konzept für MS4} +\author{Syntax Syndicate - Casono} +\begin{document} +\maketitle + + +\section{Einleitung} +Dieses Dokument beschreibt die Software-Qualitätssicherung für unser Mehrspieler-Spiel \textit{Casono}. Es wird als Teil der Programmierprojekt-Vorlesung (ehemals bekannt als cs108) an der Universität Basel von uns entwickelt.\\ + +Dieses Konzept basiert auf der \textit{DIN ISO 9126} und ist demzufolge in folgende 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} +Alle öffentlichen Klassen, Interfaces, Records und Methoden müssen durch JavaDoc dokumentiert werden.\\ +Als Teil der GitLab-Build-Pipeline wird JavaDoc auf Richtigkeit überprüft. Werden strukturelle Fehler wie ungültige Referenzen erkannt, wird der Merge verhindert.\\ +Unsere aktuelle Grundlage sind daher 0 Fehler. Für den kommenden Meilenstein ist aber unser Ziel, die Regelungen weiter zu verschärfen, sodass auch Warnungen einen Merge verhindern.\\ + +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} +Beginnend mit dem fünften Meilenstein soll diese Form ebenfalls durch einen Job in der CI-Pipeline überprüft werden. + +\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} + +\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 Teamkonventionen dokumentiert: +\begin{itemize} + \item Die Verwendung von Branches - Feature-Branches werden in \texttt{main} zusammengeführt + \item Merge-Richtlinie - CI muss bestanden werden. Keine ausdrückliche Genehmigung durch Kollegen erforderlich \footnote{Diese Regelung wird sich voraussichtlich ändern. Siehe dazu den Abschnitt zur \texttt{CODEOWNERS}-Datei.} + \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}} +Beginnend mit dem fünften Meilenstein soll eine \texttt{CODEOWNERS}-Datei erstellt werden, welche Teammitgliedern die Eigentumsrechte an bestimmten Teilen des Programmcodes zuspricht. +Wollen andere Teammitglieder Änderungen an diesen Teilen vornehmen, muss der Eigentümer sie freigeben.\\ +Aktuell ist jedoch noch unklar, ob diese Funktion genutzt werden kann, da die Instanz mindestens die \textit{Premium}-Stufe haben muss. + +\subsubsection{Automatisiertes CI-Linting und Build-Verifizierung} +Jeder Push und jede Merge-Anfrage löst die CI-Pipeline aus. + +Für Pushes und Merge-Anfrage 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} +Fehlschlagende Jobs verhindern einen Push nicht, jedoch wird ein Merge so lange verhindert, bis alle Jobs fehlerfrei abgeschlossen werden können. + +\subsection{Testverfahren} +Unit-Tests werden mit \textit{JUnit 5} geschrieben und in der Testphase der CI-Pipeline ausgeführt. Ein fehlgeschlagener Test blockiert die Merge-Anfrage. + +Als weiteres Werkzeug verwenden wir \textit{JaCoCo} für die Ermittlung der Testabdeckung. \\ +Die aktuelle Testabdeckung ist wie folgt: + +\begin{table}[H] + \centering + \renewcommand{\arraystretch}{1.4} + \begin{tabular}{L{7.5cm} r r} + \toprule + \textbf{Paketname (gekürzt)} & \textbf{Instr.\ Cov.} & \textbf{Branch Cov.} \\ + \midrule + \texttt{client.chat} & 0\,\% & 0\,\% \\ + \texttt{client.game} & 0\,\% & 0\,\% \\ + \texttt{client.network} & 3\,\% & 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} & 94\,\% & 91\,\% \\ + \texttt{server.domain.*} & 45\,\% & 37\,\% \\ + \texttt{server.network.transport} & 0\,\% & 0\,\% \\ + \texttt{server.network.protocol} & 0\,\% & 0\,\% \\ + \texttt{server.network.*} & 2\,\% & 1\,\% \\ + \midrule + \textbf{Summe} & \textbf{12\,\%} & \textbf{9\,\%} \\ + \bottomrule + \end{tabular} +\end{table} + +Unser Ziel ist es, realistische Anforderungen an unsere Testabdeckung zu stellen. +Bis zum fünften Meilenstein wollen wir daher für wichtige Bereiche, wie die Game-Engine und interne Komponenten des Netzwerks, eine möglichst hohe Abdeckung von mindestens 50\% erzielen. + +\end{document}