From ce83411b44ffce77e57fb1b834c6008f4222a3fe Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Thu, 4 Jan 2024 22:05:39 +0100
Subject: doc: Write section 'Versioning'

This section is important to communicate how to interpret version
numbers in the context of this device repository.
---
 doc/documentation.tex | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

(limited to 'doc/documentation.tex')

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 14cf828..f7c0fee 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -2,6 +2,12 @@
 \author{xengineering}
 \title{soundbox documentation}
 
+\usepackage{graphicx}
+\graphicspath{ {./diagrams/} }
+\usepackage{hyperref}
+
+\setlength\parindent{0pt}
+
 \begin{document}
 
 \maketitle
@@ -10,11 +16,34 @@
 \tableofcontents
 \newpage
 
+\listoffigures
+\newpage
+
 \chapter{Introduction}
 
 \texttt{soundbox} is a device to connect classic audio systems to the network.
 
-%\section{Versioning}
+\section{Versioning}
+
+This device is versioned with Semantic
+Versioning\footnote{\href{https://semver.org}{https://semver.org}}. The
+resulting version numbers have the format \texttt{<major>.<minor>.<patch>} like
+e.g. \texttt{2.0.3}. While Semantic Versioning is usually targeted at software
+only it is here used for the whole device. This includes mechanical, electronic
+and software aspects as shown in figure \ref{diagram:device-semver}.
+
+\begin{figure}[h]
+	\centering
+	\includegraphics[width=\textwidth]{device-semver.pdf}
+	\caption{API for a device versioned with Semantic Versioning}
+	\label{diagram:device-semver}
+\end{figure}
+
+This versioning makes sure that users do not have to care about the device
+internals at all. Devices can be seen as atomic from a user's perspective. This
+level of granularity is choosen because users are not expected to disassemble
+devices or to care about the software internals.
+
 %\section{Licensing}
 
 %\chapter{User guide}
-- 
cgit v1.2.3-70-g09d2

