Themen

Motivation: Reproduzierbarkeit von Prozessabläufen

Voraussetzung: Konsequenz und Disziplin

Kriterien für Versionsnummern-Schemata

Beispiele für Versionsnummern-Schemata

Glossar

PDF

Kapitel bei Springer

https://link.springer.com/chapter/10.1007/978-3-662-71607-6_7

• Versionsnummern und Versionverwaltung sind
  zwei voneinander unabhängige Aspekte.
• Versionsnummern (und ein Versionsverwaltungssystem)
  sind zwingende Voraussetzung für Nachvollziehbarkeit –
  und essentiell für saubere wissenschaftliche Datenanalyse.
• Versionsnummern sollten möglichst sprechend sein
  und einem klaren Schema folgen.
• Die Versionsnummer sollte an genau einem Ort abgelegt
  und nach einem festen Schema verändert werden.
• Schemata sollten konsequent befolgt werden.

Versionsnummern sind – im Zusammenspiel mit einem Versionsverwaltungssystem – zwingende Voraussetzung für Nachvollziehbarkeit und damit essentiell für die wissenschaftliche Datenanalyse. Jede produktiv zur Datenverarbeitung verwendete Version einer Software sollte deshalb eine eindeutige Versionsnummer besitzen, die am Besten automatisch mitprotokolliert wird. Gleichzeitig sollte es mit dieser Versionsnummer möglich sein, aus einem Versionsverwaltungssystem den korrespondierenden Zustand der Software wieder herzustellen.

Versionsnummern sollten dabei möglichst sprechend sein, einem klaren Schema folgen und an genau einem Ort abgelegt und nach einem festgelegten Ablauf verändert werden. In der Praxis bewährt haben sich numerische Versionsnummernschemata wie SemVer, ein automatisches Hochzählen der Versionsnummer, sowie die klare Auszeichnung von Entwicklungsversionen, die nicht produktiv für die wissenschaftliche Datenverarbeitung eingesetzt werden sollten, weil bei ihnen die Eindeutigkeit und damit die Nachvollziehbarkeit nicht gewährleistet ist.

Diese Fragen dienen der persönlichen Beschäftigung mit der Thematik, es werden aber keine Antworten zur Verfügung gestellt.

• Warum haben Versionsnummern gerade im Kontext von wissenschaftlicher
  Datenverarbeitungssoftware eine so große Bedeutung?
• Wie könnte man sicherstellen, dass Versionsnummern sauber gepflegt und immer zuverlässig sind?
• Welche Aspekte im Umgang mit Versionsnummern lassen sich automatisieren?
• Wie lassen sich (menschenlesbare) Versionsnummern in einer Versionsverwaltung sinnvoll ablegen?
• Welche Folgen ergeben sich aus der aktiven Entwicklung und einzelnen Veröffentlichungsversionen (Releases) mit klarer Versionsnummer für den Umgang mit Versionsverwaltungssystemen? Welche Bedeutung kommt hier insbesondere Zweigen (branches) zu?
• Warum ist SemVer ein gutes Beispiel für die Wirkmächtigkeit von Abstraktion (im Sinne von Dijkstra), und warum ist es so wichtig, dem Konzept wenn dann konsequent zu folgen?

Eine kommentierte und handverlesene Liste mit weiterführender Literatur zum Thema. Die Auswahl ist zwangsläufig subjektiv.

Versionsnummernschemata sind oft ein Randaspekt normaler Softwareentwicklung, auch wenn sie im Kontext der Nachvollziehbarkeit und Reproduzierbarkeit der wissenschaftlichen Datenauswertung größere Bedeutung erlangen. Es scheint relativ wenige Literatur zu geben, die darauf explizit eingeht. Für den wissenschaftlichen Kontext ist das [Taschuk, 2017Taschuk, Morgan; Wilson, Greg (2017): Ten simple rules for making research software more robust, PLoS Comput. Biol. 13:e1005412], in Kap. 25 von [Sommerville, 2018Sommerville, Ian (2018): Software Engineering, Pearson, Hallbergmoos] finden sich ebenfalls ein paar allgemeine Hinweise.

• Taschuk, Morgan; Wilson, Greg (2017): Ten simple rules for making research software more robust, PLoS Comput. Biol. 13:e1005412
• Sommerville, Ian (2018): Software Engineering, Pearson, Hallbergmoos

Es gibt viele verschiedene Schemata für die Gestaltung von Versionsnummern, und es ist nicht das Ziel des Buches, Lobbying für eines dieser Schemata zu betreiben.

Zwei konkrete Schemata werden im Buch besprochen:

• SemVer
• CalVer

Von diesen beiden ist SemVer das mit großem Abstand strukturiertere – was ihm mitunter auch vorgeworfen wird.

Auch wenn man SemVer nicht verwendet oder verwenden möchte, lohnt ein genauerer Blick auf seine Spezifikation, weil sich dort viele gute Hinweise zum generellen Vorgehen bei der Programmentwicklung finden.

Wichtig bei der Verwendung von Versionsnummernschemata: Ein Schema überlegen/entwickeln/adaptieren und dann konsequent anwenden und kommunizieren.

Um die Versionsnummern konsequent bei jedem Commit hochzuzählen, empfiehlt es sich, diesen Prozess zu automatisieren. Das nachfolgende Bash-Skript ist eine funktionierende (und vom Autor produktiv eingesetzte) Lösung für dieses Problem. Sicherlich kann man darüber streiten, ob es nicht unnötig kompliziert ist und zu viel tut, aber es funktioniert immerhin…

incrementVersion.sh

#!/bin/bash
#
# Increment version number (last part of version string)
# read from a file containing only the version number.
#
# Assuming a version number scheme following SemVer
# consisting of
#
#	MAJOR.MINOR.PATCH
#
# in which case "PATCH" is incremented,
# or alternatively
#
#	MAJOR.MINOR.PATCH.dev#
#
# where the number following "dev" is incremented.
#
# If the internal variable CHECKGIT is set to "true", the file
# containing the version string will be checked for manual changes
# and if there are any, the script will exit immediately.
#
# Copyright (c) 2017-21, Till Biskup
# 2021-04-18
 
# Some configuration
VERSIONFILE="VERSION"
CHECKGIT=true # set to "true" to check for changes via git diff
ONLYONMASTER=true
 
CURRENTBRANCH=$(git rev-parse --abbrev-ref HEAD)
 
# Internal functions
function join_by { local IFS="$1"; shift; echo "$*"; }
 
if [[ ${ONLYONMASTER} == true && ${CURRENTBRANCH} != 'master' ]]
then
  echo "Not on master branch, hence nothing to do."
  exit
fi
 
if [[ ${CHECKGIT} == true && $(git diff --name-only ${VERSIONFILE}) ]]
then
    echo "File $VERSIONFILE has been changed already..."
    exit
fi
 
 
# Read version from file
read -r oldversionstring <<< "$(cat "${VERSIONFILE}")"
 
# Split version string
IFS='.' read -r -a versionArray <<< "$oldversionstring"
 
lastPart=${versionArray[${#versionArray[@]}-1]}
 
# Check whether we need to increment a development version
# Otherwise just increment $lastPart
if [[ ${lastPart} =~ .*dev.* ]]
then
    IFS='dev' read -r -a splitLastPart <<< "$lastPart"
    revision=${splitLastPart[${#splitLastPart[@]}-1]}
    ((revision++))
    lastPart=dev${revision}
else
    ((lastPart++))
fi
 
# Reassign last part of versionArray
versionArray[${#versionArray[@]}-1]=${lastPart}
 
# Concatenate new version string
newVersionString=$(join_by . "${versionArray[@]}")
 
# Write new version string to file
echo "${newVersionString}" > ${VERSIONFILE}
 
if [[ ${CHECKGIT} == true ]]
then
    git add ${VERSIONFILE}
    echo "Version in version file upped"
fi