Die Prüfschritte des BIK BITV-Test-Prüfverfahrens stehen seit einiger Zeit öffentlich in einem Github-Repository zur Verfügung. Sie können dort von Interessierten eingesehen, kommentiert, diskutiert und kollaborativ weiterentwickelt werden. Die Weiterentwicklung der Prüfschritte ist bislang ein kontinuierlicher Vorgang, der keine Ausprägung von bestimmten Meilensteinen vorsieht. Die Einführung neuer Prüfschritte wurde zu bestimmten Zeitpunkten durchgeführt und in der Kommunikation wird dann auf den „Stand vor xx.xx.xxxx“ und den „Stand nach xx.xx.xxxx“ verwiesen.
Die bislang fehlende Referenzierbarkeit eines bestimmten Standes eines Prüfschritts kann zu zeitabhängigen Ambiguitäten beim Nachvollziehen von Bewertungen führen. Um dem entgegenzuwirken, sollen künftig eindeutige Stände des Prüfverfahrens „eingefroren“ werden, so dass eine klare Bezugnahme möglich ist.
Ein weiteres Problem für aktiv Prüfende ist, dass es derzeit nicht einfach möglich ist, Veränderungen der Prüfschritte zu erkennen und nachzuvollziehen, so dass sich die Prüfpraxis mit dem Verfahren weiterentwickeln kann. Zwar kommt die Speicherung der Prüfschritte auf Github grundsätzlich mit alle notwendigen Werkzeugen, alle Änderungen granular nachvollziehen zu können. Jedoch existiert keine anschauliche Zusammenstellung dieser Änderungen, so dass ein Gesamtbild nur mit sehr viel Mühe gewonnen werden kann.
Das vorliegende Konzept beschäftigt sich mit den Fragen:
-
Wie kann ein koordiniertes Veröffentlichen von Meilensteinen des Prüfverfahrens aussehen?
-
Wie können die Änderungen am Prüfverfahren möglichst aufwandsfrei anschaulich dargestellt werden?
-
Welche Prozesse können und sollten an die Veröffentlichung eines Meilensteins anschließen?
Im Git-Repository dieses Konzepts sowie in den Einstellungen zum Repository auf Github finden sich bereits einige prototypische Experimente, die z. T. unverändert oder mit Anpassungen in die Umsetzung des Konzepts übernommen werden können. Darüber hinaus enthält das Repository eine Kopie der Prüfschritte des BITV-Tests (Web), um realistisch damit experimentieren zu können.
Die folgenden Abschnitte stellen verschiedenen Github-Konzepte und -Funktionalitäten sowie sinnvolle Standards vor, aus denen schließlich ein Vorgehensvorschlag modelliert wird.
Git als Versionierungssystem bietet die Möglichkeit, einen bestimmten Stand einer Codebasis bzw. des Inhalts eines Git-Repositories mit einer eindeutigen Bezeichnung, einem sog. Tag zu versehen. Der betreffende Repository-Stand ist dann anhand dieses Tags eindeutig referenzierbar (Hinweis: Auch ohne Tags ist es möglich, zu jedem beliebigen vergangenen Stand eines Repositories zu springen). Ein Tag ist im Grunde eine frei wählbare, innerhalb des Repositories eindeutige Zeichenkette. In der Praxis ist es üblich, Versionsnummer als Tags zu verwenden (statt freie Texte; siehe unten).
Github als Community-Plattform bietet zusätzlich die Möglichkeit, getaggte Stände eines Repositories als sog. Releases zu veröffentlichen. Releases verfügen — neben der eindeutigen Bezugnahme auf ein Tag — zusätzlich über:
-
eine Release-Beschreibung, die beliebige Informationen zum Release transportieren kann,
-
Assets zum Release; dabei handelt es sich um beliebige Dateianhänge, beispielsweise kompilierte Softwareversionen, Dokumentationen o. ä. Github fügt standardmäßig Archive des Repository-Inhaltes in mehreren Formaten als Assets an jedes Release.
Semantische Versionierung („SemVer“) ist ein in der Open-Source-Softwareentwicklung verbreiteter und akzeptierter Standard zur Konstruktion und Vergabe von Versionsnummern. SemVer-Versionsnummern bestehen im Wesentlichen aus 3 aneinandergereihten und durch Punkte getrennte Zahlen (und möglicherweise einen Präfix sowie Suffix).
1.2.3
| | \_ PATCH-Version
| \___ MINOR-Version
\_____ MAJOR-VersionDie einzelnen Stellen in der Versionsnummer haben jeweils bestimmte Bedeutungen:
- MAJOR
-
wird erhöht, wenn API-inkompatible Änderungen veröffentlicht werden,
- MINOR
-
wird erhöht, wenn neue Funktionalitäten, welche kompatibel zur bisherigen API sind, veröffentlicht werden, und
- PATCH
-
wird erhöht, wenn die Änderungen ausschließlich API-kompatible Bugfixes umfassen.
Der Keep a Changelog-Standard setz sich für das konsequente und koordinierte Führen eines Änderungsprotokolls für jede Software ein. Er schlägt dazu bestimmte Konventionen vor:
-
Jedes Projekt sollte in seinem Wurzelverzeichnis eine Datei mit dem Namen
CHANGELOG.md(oder nurCHANGELOG) im Markdown-Format haben. -
In dieser Datei sollen — in strukturierter Form — alle nennenswerten Änderungen zu allen veröffentlichten Versionen des Projekts dokumentiert werden. Der Standard schlägt zur übersichtlichen Gliederung eine Reihe von Kategorien vor, in welche die Änderungen gruppiert werden sollen.
-
Zusätzlich ist es möglich, noch unveröffentlichte Änderungen unter einer speziellen Überschrift („Unreleased“) darzustellen, sodass eine Vorschau entsteht, was in der nächsten Veröffentlichung enthalten sein wird.
Ein Pull Request (oder Merge Request) bezeichnet in der Versionsverwaltung einen Arbeitsablauf, Quellcode-Änderungen in Softwareprojekten vorzunehmen. Ziel eines Pull Requests ist, Änderungen aus einem Branch (also einer abgeleiteten Arbeitsversion) in die eigentliche Quellcode-Basis zu übernehmen. Wird ein Pull Request akzeptiert, so spricht man von einem Merge, wird er geschlossen, so spricht man von einem Close.
Beim BITV-Test-Prüfverfahren stellen Pull Requests den Standard-Weg dar, auf dem Änderungen in die Prüfschritte eingehen (sollen). Community-Mitglieder (oder die Projekt-Verwaltenden selbst) entwerfen Änderungsvorschläge für die Prüfschrittbescheibungen und übertragen diese in individuellen Branches ins Repository. Sie reichen die Änderungen als Anträge zur Übernahme in den Haupt-Branch ein. In diesem Zug müssen sie wenigstens einen Titel für ihren Pull Request angeben und haben zusätzlich die Möglichkeit, eine ausführlichere Erläuterung als Nachricht beizufügen (was beim BITV-Test selten vorkommen dürfte, da der Titel in der Regel genug Aussage transportieren kann).
Nicht selten sind Pull Requests das Ergebnis einer Themendiskussion (Issue) oder gehen damit einher. Sowohl Issues, als auch Pull Requests sind auf Github dauerhaft einsehbar — auch nachdem sie übernommen oder geschlossen wurden.
|
Caution
|
Neben der Möglichkeit, Änderungen per Pull Request in die Quellcode-Basis einzubringen, können diese auch direkt in den Haupt-Branch übertragen werden. Wird dies zugelassen, besteht die Gefahr, dass Änderungen Eingang finden, die nicht ausreichend geprüft wurden und (bei Softwareprojekten) zu ernsthaften Problemen führen können. Diese Möglichkeit sollte daher allenfalls Verwaltenden mit einer besonderen Vertrauensstellung und mit viel Erfahrung vorbehalten sein. Im Idealfall wird durch entsprechende Einstellungen dafür gesorgt, dass eine direkte Veränderung der Code-Basis generell nicht möglich ist. |
Um die Bearbeitungsabläufe benutzerfreundlich zu gestalten, bietet Github an, Issues und Pull Requests mit Etiketten, sog. Labels zu versehen. Die Labels können mit einer Farbe assoziiert und frei angelegt werden (Github bringt eine Standard-Vorauswahl mit, die jedoch verworfen oder verändert werden kann). Labels machen es einfach, Themen zu kategorisieren, priorisieren oder anderweitig zu organisieren. Sie dienen rein der Oberflächennutzung und haben keine funktionale Auswirkung auf die Quellcode-Basis.
Github Actions bringen die Möglichkeit, beim Eintreten bestimmter Ereignisse in einem Repository nahezu beliebige Prozesse anzustoßen und ablaufen zu lassen. Beispielsweise können beim Einreichen von neuem Code automatisierte Tests die Gültigkeit und Funktionstüchtigkeit der neuen Programmierung prüfen und Alarm schlagen, sollte ein Problem erkannt werden. Oder es können beim Veröffentlichen eines Releases Kompilierschritte vollzogen werden, die für die lauffähige Form der Software notwendig sind.
Github Actions führen dazu sog. Workflows aus, die in YAML-Dateien artikuliert und direkt im Repository gespeichert werden. Die Funktionalität steht für öffentliche Repositories kostenfrei zur Verfügung.
Aufbauend auf den oben dargestellten Tools und Standards wird folgender Vorgehensvorschlag unterbreitet.
- Prüfschritt-Änderungen nur über Pull Requests
-
Es wird festgelegt, dass Änderungen an den Prüfschritten ausschließlich über Pull Requests erfolgen dürfen. Direktes Übertragen von Code-Änderungen in den Haupt-Branch ist allenfalls zur technischen Administration und zum Ändern der Programmierteile des Repositories (z. B. Github-Action-Workflows) gestattet. Pull Requests sind generell so granular wie möglich zu halten. Zulässig sind nur Änderungen an einem Prüfschritt je Pull Request.
- Pull-Request-Titel
-
Die Betitelung von Pull Requests unterliegt besonderen Regeln und ist mit entsprechender Sorgfalt durchzuführen, da die Titel für die automatische Erzeugung von Release-Notizen sowie zur Aktualisierung des Änderungsprotokolls herangezogen werden. Da die Titel initial von den Antragstellenden verfasst werden, ist es Aufgabe der Verwaltenden, die Formulierung der Titel auf die Richtlinie hin zu prüfen und ggf. anzupassen, bevor ein Pull Request akzeptiert wird.
- Labels für Pull Requests
-
Jedem Pull Request sind zwei Label aus zwei vorgegebenen Taxonomien zu vergeben:
-
In Abhängigkeit davon, wie gravierend die Änderungen sind, die mit dem Pull Request einhergehen, steuert ein Versionierungs-Label (
version:*), ob sich daraus eine PATCH-, MINOR- oder MAJOR-Versionsänderung ergeben sollt. Wird kein Versionierungs-Label vergeben, so wird automatisch eine PATCH-Versionsänderung hervorgerufen. -
Ein Änderungsprotokoll-Label (
changelog:*) ordnet den Pull Requests in eine der 6 Kategorien ein, in die Änderungen im Änderungsprotokoll gruppiert werden. Wird kein Änderungsprotokoll-Label vergeben, so wird der Pull Request nicht im Änderungsprotokoll erwähnt (kann in Ausnahmesituationen gezielt genutzt werden).
-
- Periodische Releases
-
Die Prüfschritte des BITV-Test-Prüfverfahrens werden in regelmäßigen Abständen — vorgeschlagen wird ein quartalsweiser oder 2-monatiger Rhythmus — als neues Release veröffentlicht. Die Veröffentlichung erfolgt automatisiert über Github Actions und wird durch ein Scheduler-Ereignis angestoßen (zeitplanbasiert). Bestandteil eines Releases sind stets alle Pull Requests (und Direktänderungen der Code-Basis) seit der Veröffentlichung des letzten Releases.
- Bei Bedarf: Manuelle Releases
-
Für Ausnahmesituationen (z. B. bei dringender notwendiger Anpassung) besteht zusätzlich die Möglichkeit, auch außerhalb des regulären Takts manuell Releases zu veröffentlichen. Der eigentliche Vorgang ist mit einem periodischen Release identisch.
- Versionsnummer
-
Jedes Release erhält eine eindeutige Versionsnummer nach dem Standard der Semantischen Versionierung. Zur automatischen Bestimmung der neuen Versionsnummer werden die Versionierungs-Label der im Release erhaltenen Pull Requests betrachtet. Größere Versionssprünge überwiegen kleinere. Das heißt, verlangt ein Pull Request über sein
version:*-Label eine PATCH-Veränderung, ein anderer dagegen eine MINOR-Veränderung, so wird dies zu einer Anhebung der MINOR-Stelle der Versionsnummer führen (die PATCH-Stelle wird dabei auf 0 zurückgesetzt).
- Automatische Release-Notizen
-
Beim Erstellen des Releases werden automatisch Release-Notizen generiert. Es werden sämtliche im Release enthaltenen Pull Requests aufgenommen, die über ein Änderungsprotokoll-Label verfügen. Die einzelnen Pull Requests werden unter Angabe ihres Titels, ihres Autors bzw. ihrer Autorin (verlinktes Github-Handle) sowie der verlinkten Pull-Request-ID dargestellt. Die Einträge werden anhand der Änderungsprotokoll-Label gruppiert. Die Release-Notizen werden durch einen Face-Pile der am Release beteiligten Mitwirkenden abgeschlossen. Beispiele finden sich im Releases-Bereich dieses Repositories.
- Automatische Aktualisierung des Änderungsprotokolls
-
Im Zuge der Release-Erstellung wird auch das Änderungsprotokoll des Repositories aktualisiert. Die Inhalte der Release-Notizen werden, vom Mitwirkenden-Face-Pile abgesehen, 1:1 ins Änderungsprotokoll übernommen und zusammen mit der Release-Version und dem Veröffentlichungsdatum wiedergegeben.
- Optional: Automatische Release-Assets
-
Es ist denkbar, einem Release vor der veröffentlichung zusätzliche Assets anzuhängen, etwa eine versionierte, dynamisch generierte PDF/UA-Gesamtversion des kompletten Prüfverfahrens mit allen Prüfschritten.
- Automatische Release-Folgeaktionen
-
Sobald ein Release veröffentlicht wurde, können an dieses Ereignis weitere Prozessketten anschließen. Beispielsweise müssen dann die Prüfschrittbeschreibungen im BITV-Test-Studio aktualisiert und auf den neuesten Stand gebracht werden. Es lassen sind jedoch auch viele weitere Anschlussaktionen denkbar.
Das dargestellte Release-Konzept ist, von den optionalen Teilen und Vorschlägen abgesehen, in diesem Repository bereits prototypisch umgesetzt, grundsätzlich einsatzfähig und demonstrierbar.
|
Note
|
Aufgrund eines bekannten Problems in einem beteiligten Modul kann die Veröffentlichung von Releases derzeit noch nicht vollautomatisch angestoßen werden. Zumal aber ohnehin nur ein quartalsweiser Zeittakt vorgschlagen wird, scheint es zumutbar, die Veröffentlichung von Releases bis zur Behebung des Problems manuell anzustoßen. |
-
❏ Verfassen einer Richtlinie zum Beitragen zum Repository in einer
CONTRIBUTING.mdim Wurzelverzeichnis. Es handelt sich dabei um eine Praxis, die im Open-Source-Umfeld bekannt und üblich ist. Darin sollten bestimmte Grundlagen festgehalten sein:-
Änderungen an nur einem Prüfschritt je Pull Request
-
Betitelung von Pull Requests
-
usw.
-
-
❏ Anlegen eines Pull-Request-Templates, indem die wesentlichen Richtlinien auch nochmal direkt im Kontext des Anlegens eines Pull Requests verdeutlicht werden.
Damit die Wiedergabe von Änderungen in den Release-Notizen sowie im Änderungsprotokoll möglichst sinnvoll sind, sollten Pull Requests konsequent, einheitlich und aussagekräftig betitelt werden. Es wird daher vorgeschlagen, folgendes Format einzuhalten:
<Prüfschritt-Nummer> <Prüfschritt-Bezeichnung>: <Kurzbeschreibung-Änderung>Beispiel:
9.1.1.1a Alternativtexte für Bedienelemente: Textkorrekturen
In den Release-Notizen sowie im Änderungsprotkoll wird dies zusätzlich mit interaktiven Verweisen auf die\*den Beitragende\*n sowie den Pull Request versehen. Beispiel:
9.1.1.1a Alternativtexte für Bedienelemente: Textkorrekturen @sweckenmann (#6)
Die folgenden Assets könnten bei der Veröffentlichung eines Releases erzeugt und angehängt werden:
-
❏ PDF/UA-Gesamtausgabe des Prüfverfahrens (siehe Release-Aktionen)
Die folgenden Prozessketten könnten / sollten sich an das Veröffentlichen eines neuen Releases (automatisiert) anschließen.
-
✓ Aktualisieren der Prüfschrittbeschreibungen im BITV-Test-Studio (bereits implementiert)
-
❏ Aktualisieren der Prüfschrittbeschreibungen auf der zukünftigen Microsite (vorbereitet)
-
❏ Erzeugen und Archivieren einer PDF/UA-Gesamtausgabe des Prüfverfahrens auf der Microsite (zur Verlinkung in Prüfberichten u.ä.)
-
❏ Erzeugen eines News-Beitrags auf der Microsite (mit Inhalt der Release-Notizen)
-
❏ Erzeugen eines RSS-Feed-Eintrags (Microsite?) zur Darstellung im BITV-Test-Studio
-
❏ Versand eines E-Mail-Newsletters and die Prüfer-Mailingliste